TypedParameters.Dapper.SqlServer 1.0.1

Dapper.TypedParameters

English | Português (Brasil)

Dapper.TypedParameters.SqlServer provides explicit SQL Server parameter metadata for Dapper using Microsoft.Data.SqlClient.

Use it when the database contract is known and the SQL Server parameter type, size, precision, scale, direction, or table-valued parameter type name should be visible at the call site.

Installation

Install the latest stable package from NuGet.org:

dotnet add package TypedParameters.Dapper.SqlServer

Official package page: TypedParameters.Dapper.SqlServer on NuGet.org

For a reproducible 1.0.0 install:

dotnet add package TypedParameters.Dapper.SqlServer --version 1.0.0

The NuGet package identity is separate from the assembly and namespace:

NuGet package: TypedParameters.Dapper.SqlServer
Assembly: Dapper.TypedParameters.SqlServer.dll
Namespace: Dapper.TypedParameters.SqlServer

Minimal Example

using Dapper;
using Dapper.TypedParameters.SqlServer;
using Microsoft.Data.SqlClient;

await using var connection = new SqlConnection(connectionString);

var customer = await connection.QuerySingleOrDefaultAsync<Customer>(
    """
    SELECT Id, Document, Name
    FROM dbo.Customers
    WHERE Document = @Document;
    """,
    new
    {
        Document = SqlParam.VarChar(document, 11)
    });

.NET string
  -> explicit SQL metadata
  -> SQL Server varchar(11) parameter

Why?

Dapper parameter inference is correct and convenient for many scenarios. The trade-off is that the SQL Server metadata sent to the provider is not always obvious in the calling code.

When code already knows the database contract, explicit metadata can make that contract visible:

new
{
    Document = document
}

new
{
    Document = SqlParam.VarChar(document, 11)
}

The second form does not claim that varchar is universally better than nvarchar. It says that this parameter is intended to match a known varchar(11) contract.

The Problem

SQL Server evaluates parameters using SQL type metadata, not only CLR values. A metadata mismatch can cause SQL Server conversions depending on the involved types, type precedence, collation, query shape, indexes, and execution plan.

This library gives the caller control over the parameter metadata sent through Microsoft.Data.SqlClient. It does not guarantee faster queries, remove every implicit conversion, or analyze execution plans. Measure performance-sensitive queries in your own workload.

Supported Parameter Types

Compatibility

The SQL Server and Azure SQL entries describe Microsoft.Data.SqlClient driver compatibility. This repository currently integration-tests only the SQL Server 2022 container image listed above.

Documentation

• Getting started
• Motivation
• Examples:
  • Strings
  • Numeric
  • Binary and identifiers
  • Temporal
  • Output parameters
  • Table-valued parameters
• Português (Brasil)

Design Principles

• Make SQL Server parameter metadata explicit at the call site.
• Keep the public API small and predictable.
• Use Microsoft.Data.SqlClient directly.
• Preserve ordinary Dapper calling patterns.
• Prefer explicit factory methods over automatic SQL type selection.

What This Library Does Not Do

The library does not:

• inspect your database schema;
• query SQL Server for metadata;
• rewrite SQL;
• analyze execution plans;
• detect CONVERT_IMPLICIT;
• automatically choose SQL types;
• map POCOs to table-valued parameters;
• create SQL Server user-defined table types;
• support System.Data.SqlClient.

Testing and Quality

The repository validates unit tests, SQL Server integration tests, package contents, package consumption, public API baselines, SourceLink, package validation, and SonarQube Cloud Quality Gate checks for the supported target frameworks.

Basic local validation:

dotnet restore Dapper.TypedParameters.sln
dotnet build Dapper.TypedParameters.sln --configuration Release --no-restore
dotnet test Dapper.TypedParameters.sln --configuration Release --no-build
dotnet pack src/Dapper.TypedParameters.SqlServer/Dapper.TypedParameters.SqlServer.csproj --configuration Release --no-build --output artifacts/packages

Integration tests use SQL Server through Docker and Testcontainers.MsSql.

Release Registries

The protected release workflow publishes the same validated .nupkg to NuGet.org, the primary public installation source, and GitHub Packages, the repository-linked secondary registry. A rehearsal with publish=false never publishes; publish=true requires the matching version tag and approval of the nuget-release environment. NuGet.org uses Trusted Publishing, while GitHub Packages uses the ephemeral workflow GITHUB_TOKEN. After its first publication, the GitHub package must be made public explicitly before it can be consumed anonymously.

Contributing

Issues and pull requests are welcome. Please keep changes small, explicit, and validated for both supported target frameworks.

License

This project is licensed under the MIT license.

Disclaimer

This project is not affiliated with, maintained by, or officially endorsed by the Dapper project or Microsoft.