Install
You use Dapper: start with Use Dapper. Your database is not PostgreSQL or SQL Server: start with another database.
At the end of this page, your project has the SqlSource NuGet package, and your repository has the tool, on a supported .NET version. Your project also has the driver package of your database.
Requirements
- Your project targets .NET 8 or later, and C# 12 or later.
- You build it with the .NET SDK 9.0.300 or later, or with Visual Studio 2022 17.14 or later.
- Your database is PostgreSQL 14 or later, or SQL Server 2017 or later, as supported versions lists.
- The
sqlsourcetool needs the .NET SDK, not only the .NET runtime.
If your .NET SDK or Visual Studio is older, the build stops with SQLSRC021. Update the .NET SDK to 9.0.300 or later, or Visual Studio to 2022 17.14 or later. If a global.json file pins an older SDK, change the version it pins. Your project can still target .NET 8.
Add the package
In the folder of each project that has queries, add the SqlSource package:
$ dotnet add package SqlSource
Then add the driver package of your database to the same project:
$ dotnet add package Npgsql
Each command adds a PackageReference to your project file.
Install the tool
Do this once, in the folder at the root of your repository:
$ dotnet new tool-manifest
$ dotnet tool install SqlSource.Tool
If your repository already has a tool manifest, leave out the first command. The second command adds the tool to the manifest, dotnet-tools.json, and prints that the tool was installed.
- Commit
dotnet-tools.json. A colleague who clones the repository runsdotnet tool restoreto get the same tool. - Keep the tool at the version of the
SqlSourcepackage. When you update the package, rundotnet tool update SqlSource.Tool.
If the tool and the package have different versions, the tool can report SQLSRC206. Update the older of the two.
What each package adds to your project
SqlSourceruns inside the compiler when you build. It adds no runtime dependency: no SqlSource assembly ships with your application. Your project compiles only the code it generates, with the attributes you write and the exceptions its methods throw.SqlSource.Tooladds thesqlsourcecommand to your repository. It describes your queries, as the next page shows.
If it does not work
- SQLSRC021: your .NET SDK or Visual Studio is too old. Update it, as Requirements says.
- SQLSRC267: on SQL Server, your project references Microsoft.Data.SqlClient older than 6.1. Reference 6.1 or later.
- SQLSRC206: the tool and the package have different versions. Update the older one.
What you have now
A project that references SqlSource and your driver, and a repository whose tool manifest has the sqlsource tool.
Rules: what the build needs, supported versions, install the tool, what the tool needs, what the package adds, SQLSRC267 with EF Core.
Next: Your first query