Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update readme for 3.1.0 & add SQLCLR section #706

Merged
merged 1 commit into from
Feb 4, 2025
Merged

Update readme for 3.1.0 & add SQLCLR section #706

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 27 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ dotnet new sqlproj -s Sql130
You should now have a project file with the following contents:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
<SqlServerVersion>Sql150</SqlServerVersion>
Expand Down Expand Up @@ -132,7 +132,7 @@ If you already have a SSDT (.sqlproj) project in your solution, you can keep tha
There are a lot of properties that can be set on the model in the resulting `.dacpac` file which can be influenced by setting those properties in the project file using the same name. For example, the snippet below sets the `RecoveryMode` property to `Simple`:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
<RecoveryMode>Simple</RecoveryMode>
Expand All @@ -151,7 +151,7 @@ Like `.sqlproj` projects `MSBuild.Sdk.SqlProj` supports controlling T-SQL build
Treating warnings as errors can be optionally enabled by adding a property `TreatTSqlWarningsAsErrors` to the project file:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TreatTSqlWarningsAsErrors>True</TreatTSqlWarningsAsErrors>
...
Expand All @@ -164,7 +164,7 @@ Treating warnings as errors can be optionally enabled by adding a property `Trea
To suppress specific warnings from being treated as errors, add a comma-separated list of warning codes to `SuppressTSqlWarnings` property in the project file:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<SuppressTSqlWarnings>71558,71502</SuppressTSqlWarnings>
<TreatTSqlWarningsAsErrors>True</TreatTSqlWarningsAsErrors>
Expand All @@ -176,7 +176,7 @@ To suppress specific warnings from being treated as errors, add a comma-separate
You can suppress warnings for a specific file by adding `SuppressTSqlWarnings` for this file:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
...
</PropertyGroup>
Expand All @@ -197,7 +197,7 @@ You can suppress warnings for a specific file by adding `SuppressTSqlWarnings` f
To include these scripts into your `.dacpac` add the following to your `.csproj`:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
...
</PropertyGroup>
Expand All @@ -214,7 +214,7 @@ It is important to note that scripts in the `Pre-Deployment` and `Post-Deploymen
By default the pre- and/or post-deployment script of referenced packages (both [PackageReference](#package-references) and [ProjectReference](#project-references)) are not run when using `dotnet publish`. This can be optionally enabled by adding a property `RunScriptsFromReferences` to the project file as in the below example:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<RunScriptsFromReferences>True</RunScriptsFromReferences>
...
Expand All @@ -231,7 +231,7 @@ By default the pre- and/or post-deployment script of referenced packages (both [
Especially when using pre- and post-deployment scripts, but also in other scenario's, it might be useful to define variables that can be controlled at deployment time. This is supported using SQLCMD variables. These variables can be defined in your project file using the following syntax:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
...
</PropertyGroup>
Expand All @@ -256,7 +256,7 @@ Especially when using pre- and post-deployment scripts, but also in other scenar
`MSBuild.Sdk.SqlProj` supports referencing NuGet packages that contain `.dacpac` packages. These can be referenced by using the `PackageReference` format familiar to .NET developers. They can also be installed through the NuGet Package Manager in Visual Studio.

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
</PropertyGroup>
Expand All @@ -270,7 +270,7 @@ Especially when using pre- and post-deployment scripts, but also in other scenar
It will assume that the `.dacpac` file is inside the `tools` folder of the referenced package and that it has the same name as the NuGet package. Referenced packages that do not adhere to this convention will be silently ignored. However, you have the ability to override this convention by using the `DacpacName` attribute on the `PackageReference` (introduced in version 2.5.0). For example:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
<SqlServerVersion>Sql160</SqlServerVersion>
Expand All @@ -287,7 +287,7 @@ This will add a reference to the `tools\SomeOtherDacpac.dacpac` file inside the
By default, the package reference is treated as being part of the same database. For example, if the reference package contains a `.dacpac` that has a table and a stored procedure and you would `dotnet publish` the project the table and stored procedure from that package will be deployed along with the contents of your project to the same database. If this is not desired, you can add the `DatabaseVariableLiteralValue` item metadata to the `PackageReference` specifying a different database name:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
</PropertyGroup>
Expand All @@ -304,7 +304,7 @@ You can also use SQLCMD variables to set references, similar to the behavior of
>Note: Don't forget to define appropriate [SQLCMD variables](#sqlcmd-variables)

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
</PropertyGroup>
Expand Down Expand Up @@ -347,7 +347,7 @@ sqlpackage
Microsoft has released NuGet packages containing the definitions of the `master` and `msdb` databases. This is useful if you want to reference objects from those databases within your own projects without getting warnings. To reference these, you'll need to use at least version 2.5.0 of MSBuild.Sdk.SqlProj as you'll need to use the `DacpacName` feature for package references described above. For example:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
<SqlServerVersion>160</SqlServerVersion>
Expand All @@ -368,7 +368,7 @@ For other variants of SQL Server / Azure SQL Database there are dedicated packag
Similar to package references you can also reference another project by using a `ProjectReference`. These references can be added manually to the project file or they can be added through Visual Studio. For example, consider the following example:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
</PropertyGroup>
Expand All @@ -382,7 +382,7 @@ Similar to package references you can also reference another project by using a
This will ensure that `MyOtherProject` is built first and the resulting `.dacpac` will be referenced by this project. This means you can use the objects defined in the other project within the scope of this project. If the other project is representing an entirely different database, you can also use `DatabaseVariableLiteralValue` or SQLCMD variables on the `ProjectReference` similar to `PackageReference`:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
</PropertyGroup>
Expand Down Expand Up @@ -416,7 +416,7 @@ In order to solve circular references between databases that may have been incor
`SuppressMissingDependenciesErrors` to both [Package References](#package-references) and [ProjectReferences](#project-references)):

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
</PropertyGroup>
Expand All @@ -438,7 +438,7 @@ In order to solve circular references between databases that may have been incor
You'll need to set the `PackageProjectUrl` property in the `.csproj` like this:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
...
<PackageProjectUrl>your-project-url</PackageProjectUrl>
Expand Down Expand Up @@ -513,7 +513,7 @@ To further customize the deployment process, you can use the following propertie
In addition to these properties, you can also set any of the [documented](https://docs.microsoft.com/dotnet/api/microsoft.sqlserver.dac.dacdeployoptions) deployment options. These are typically set in the project file, for example:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
...
<BackupDatabaseBeforeChanges>True</BackupDatabaseBeforeChanges>
Expand All @@ -537,7 +537,7 @@ Most of those properties are simple values (like booleans, strings and integers)
Instead of using `dotnet publish` to deploy changes to a database, you can also have a full SQL script generated that will create the database from scratch and then run that script against a SQL Server. This can be achieved by adding the following to the project file:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<GenerateCreateScript>True</GenerateCreateScript>
<IncludeCompositeObjects>True</IncludeCompositeObjects>
Expand Down Expand Up @@ -565,7 +565,7 @@ Starting with version 2.7.0 of the SDK, there is support for running static code
Static code analysis can be enabled by adding the `RunSqlCodeAnalysis` property to the project file:

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
Expand Down Expand Up @@ -597,7 +597,7 @@ Any rule violations found during analysis are reported as build warnings.
Individual rule violations or groups of rules can be configured to be reported as build errors as shown below.

```xml
<Project Sdk="MSBuild.Sdk.SqlProj/3.0.0">
<Project Sdk="MSBuild.Sdk.SqlProj/3.1.0">
<PropertyGroup>
<RunSqlCodeAnalysis>True</RunSqlCodeAnalysis>
<CodeAnalysisRules>+!SqlServer.Rules.SRN0005;+!SqlServer.Rules.SRD*</CodeAnalysisRules>
Expand Down Expand Up @@ -692,6 +692,12 @@ While the SDK does not help you maintain a [refactor log](https://learn.microsof
</ItemGroup>
```

## SQL CLR objects support

It is not possible to include SQL CLR objects in `MSBuild.Sdk.SqlProj` projects, as they can only be built on .NET Framework.

You can work around this by "isolating" your SQL CLR objects in a separate `.sqlproj` project, build and pack the resulting `.dacpac` in a NuGet package on Windows, and then reference this package from your project. Read more about this approach in [this blog post](https://erikej.github.io/dacfx/sqlclr/2025/01/28/dacfx-sqlclr-msbuild-sdk-sqlproj.html).

## Known limitations

Since this is not an entire project system but only an MSBuild SDK we cannot provide IntelliSense for objects defined within the project. This limitation can be circumvented by connecting the SQL editor to a live database that is used for development purposes.