Table of Contents

Attributes

The three attributes

SqlSource has three attributes that you write on your code. This table gives each attribute, its properties and the section that tells how to use them.

Attribute Property Section
[SqlSourceGenerate] Source The attribute, Source
[SqlSourceGenerate] GenerateInterface, InterfaceName Repository interfaces
[SqlSourceConnection] Database The connection, a factory that a repository holds, a static member of the project
[SqlSourceConverter] No property Converters

The attribute

[SqlSourceGenerate(Source = "Queries")]
internal static partial class Reports;

[SqlSourceGenerate] marks a type that the generator adds members to. The package adds this attribute, two other attributes and three exceptions to your project, in the namespace SqlSource: see what the package adds.

  • It goes on a class, a struct, a record or a record struct. The type can be static, generic, or nested in other types.
  • The queries of a static type need an output other than repository (SQLSRC034). A static type has no instance. So in the sample, the files of Reports must set the output methods, models or sql.
  • The type and every type that contains it must be partial (SQLSRC001). The generator adds its members in a second declaration of each.
  • Neither the type nor a type that contains it can be file (SQLSRC002).
  • A type with an error gets no members, and asks for no models. Your code that uses its members then fails to compile too. So fix the first error that the build reports.

The attribute has three properties:

Property Sets
Source Which .sql files the type claims: Source
GenerateInterface Whether a repository gets its interface, over the project's choice: repository interfaces
InterfaceName The name of a repository's interface, IUserRepository by default: repository interfaces

Every other setting of a query comes from its .sql file, through its markers and the settings files of its folder. It does not come from the type that claims the query. This is true of the output of the query and of where its members go.

Which files belong to a type

Repository/
    UserRepository.cs      [SqlSourceGenerate] on UserRepository
    UserRepository.sql     belongs to UserRepository: the file named for it
    Orders.sql             not UserRepository's: another name
    Reports/
        Monthly.sql        not searched: it is in a subfolder

A type claims the file named for it, beside the C# file that carries the attribute, or the files that its Source names. Source = "." claims every .sql file of that folder. Source gives the rules and the errors. This section says what the generator does with the files that a type claims.

  • The files of a type are one set. A query name can be used only once across all of them. A second use is SQLSRC008. The file with the second use then gets no members and no models for that type.
  • Two types can claim one file. Each type gets its own members from it. Two types of one namespace can give one method twice: see where the methods go.
  • Two types that claim one file take the same settings from it. Every setting of a query comes from the file and its settings files. So both types get one output, one member location, one suffix and one shape of model. A type that needs other settings needs a file of its own.
  • Two types in one namespace share the models of the queries of the file. Two types in two namespaces get a model each, unless the namespace of the models gives them one (shared models).
  • A .sql file that no type claims is ignored: see Source.
  • A file with an error in how it is written produces no members until you fix it: see .sql files. The other files of the type are unaffected.
  • An error about describing a query, or about its sidecar, leaves the query without models until you fix it. SQLSRC241 is such an error.
    • Under repository or methods, the query then gets no method.
    • Under models, the query keeps its constant or token method.

Source

[SqlSourceGenerate]                                  // UserRepository.sql, beside this C# file
public partial class UserRepository;

[SqlSourceGenerate(Source = ".")]                    // every .sql file beside this C# file
public partial class StoreQueries;

[SqlSourceGenerate(Source = "Queries/Users.sql")]    // one file
public partial class UserQueries;

[SqlSourceGenerate(Source = "../Queries")]           // the .sql files of a folder
public partial class SharedQueries;

Source says which .sql files a type claims. It is a property of the attribute, and you can write it nowhere else.

  • A Source that ends in .sql names one file.
  • Any other Source names a folder, and the type claims the .sql files of that folder. Source = "." is every .sql file in the folder of the C# file. SqlSource does not search subfolders.
  • Without Source, the type claims the one .sql file named for it. The file is in the folder of the C# file that carries the attribute: UserRepository.sql for UserRepository.
  • The name of that file is the name of the type itself, without its type parameters. So Repository<T> claims Repository.sql, and a nested type Outer.Inner claims Inner.sql.
  • For a partial type, the folder is the folder of the file that carries the attribute.
  • An empty Source, Source = "", is the same as no Source.
  • A Source of white space is not the same as no Source. SqlSource reads it as the name of a folder, like any other Source, so it matches nothing.
  • Source is relative to the folder of the C# file, never to the project. Both / and \ separate folders.
  • SqlSource ignores case when it compares paths, so that a project builds the same on every operating system. Two .sql files whose paths differ only by case are SQLSRC013 when a type claims that path.
  • A Source that matches nothing is SQLSRC004.
  • If there is no Source, and no file is named for the type, that is SQLSRC005.
  • Two types can claim one file: see which files belong to a type.
  • A .sql file that no type claims is ignored. So a folder of migration scripts elsewhere in the project does no harm.

A type can claim only a file that the project includes. Which files the compiler is given is a separate rule, and it applies first. The attribute itself is described under the attribute.

What the package adds to your project

SqlSource is the generator. Add the package to each project whose queries you want generated.

  • The package adds no runtime dependency. The generator runs in the compiler when you build. No assembly of it ships with your application, and it is not a dependency of a package that you build.
  • Only what the generator writes is compiled into your project. That is the code it generates for your queries, and the types in this list.
  • Three attributes, as internal types in the namespace SqlSource:
  • Three exceptions that a query method throws, as internal types in the namespace SqlSource: UnexpectedRowCountException, TransactionRolledBackException and CollectionItemException.
  • Microsoft.CodeAnalysis.EmbeddedAttribute, an internal attribute, in the generated file SqlSource-EmbeddedAttribute.g.cs. It keeps the three attributes out of sight of other projects, but not the exceptions. If your project declares it too, see the limit.
  • Code that uses these types needs using SqlSource; and nothing else.

Limits

SQLSRC208, and nothing is described, for a type whose Source is a constant or nameof

What you see. One of these:

  • sqlsource describe reports SQLSRC208 and describes nothing for the type. The Source of the type is a constant, nameof, a concatenation or a cast. The build then reports SQLSRC241 for each query of the type that needs an entry in its sidecar and has none. Under a dialect that has no database to ask, such as ansi, the build reports SQLSRC209 for the file instead.
  • The type is marked with an alias of the attribute (using Gen = SqlSource.SqlSourceGenerateAttribute; and [Gen]). The alias works in the build, but the tool does not see it. So the tool does not describe the queries of the type, and the build reports SQLSRC241 for them in the same way.

Why. The tool reads the attribute without compiling your code. sqlsource describe finds [SqlSourceGenerate] by reading your C# files as text. So the tool can read Source only when it is written out where the attribute is, as a string: Source = "Queries". A constant, nameof, a concatenation or a cast there compiles, but the tool cannot read it. For the same reason, the tool reads an attribute inside #if with the compilation constants that it gets from your project. These can differ from the constants of the configuration that you build.

What to do.

  1. Write Source as a string where the attribute is.
  2. Write the attribute under its own name.
  3. Write the attribute outside #if where you can.

A compile error about Microsoft.CodeAnalysis.EmbeddedAttribute

What you see. The build fails with the compiler's errors about your declaration of Microsoft.CodeAnalysis.EmbeddedAttribute. You get one of these, each with more errors after it:

  • CS0260 when it is not partial;
  • CS0262 when it is public;
  • CS0263 when it derives from another class;
  • CS0441 when it is static;
  • CS0261 when it is a record.

Why. SqlSource adds internal sealed partial class EmbeddedAttribute : System.Attribute, in the namespace Microsoft.CodeAnalysis, to every project. A project that declares Microsoft.CodeAnalysis.EmbeddedAttribute itself compiles only when its declaration can be joined to SqlSource's. This is true of a declaration in your code, and of one in code that another package adds to your project. The declaration must be an internal partial class that derives from System.Attribute or names no base class, sealed or not. SqlSource cannot report the problem before the compiler does.

What to do. Make the declaration an internal partial class, or remove it.