SolGrpUnltd.Tools_TSQL 0.0.0

SolGrpUnltd.Tools_TSQL

A robust .NET library providing TSQL database operations with built-in Polly resilience and retry capabilities for SQL Server connections.

Overview

SolGrpUnltd.Tools_TSQL is a production-ready library designed to simplify SQL Server database operations while ensuring reliability through automatic retry logic for transient failures. The library leverages Polly for resilience patterns, including exponential backoff and jitter for optimal retry behavior.

Features

• Automatic Retry Logic: Built-in retry mechanisms for transient SQL Server errors (timeouts, deadlocks, connection issues)
• Polly Integration: Leverages Microsoft.Extensions.Resilience and Polly for robust error handling
• Multiple Authentication Types: Supports Windows Authentication, SQL Authentication, and Azure AD authentication
• Flexible API: Supports both standard and resilient (retry-enabled) method variants
• Windows Impersonation Support: Execute queries with specific Windows credentials
• Type-Safe Operations: Strongly-typed methods for common scalar returns (Int, String, etc.)
• Connection String Builder: Easy-to-use SQLServerConn model for connection configuration

Target Frameworks

• .NET 8.0
• .NET 10.0
• .NET 10.0 with Windows 10.0.26100.0 support

Installation

Install via NuGet Package Manager:

dotnet add package SolGrpUnltd.Tools_TSQL

Or via Package Manager Console:

Install-Package SolGrpUnltd.Tools_TSQL

Usage

Basic Query Execution

using SolGrpUnltd.Tools;

// Execute scalar query returning an integer
string connectionString = "Server=myserver;Database=mydb;Integrated Security=true;";
string query = "SELECT COUNT(*) FROM Users";

int userCount = SQLData.ExecuteScaler_Int(connectionString, query);

Resilient Query Execution with Automatic Retry

using SolGrpUnltd.Tools;

// Execute with automatic retry on transient failures
string connectionString = "Server=myserver;Database=mydb;Integrated Security=true;";
string query = "SELECT COUNT(*) FROM Users";

// Retry with default settings (3 retries, 750ms initial delay with exponential backoff)
int userCount = SQLData.rExecuteScaler_Int(connectionString, query);

// Customize retry behavior
int userCount = SQLData.rExecuteScaler_Int(
    connectionString, 
    query, 
    commandTimeout: 120,
    retries: 5,
    delay_ms: 1000
);

Using SQLServerConn for Connection Management

using SolGrpUnltd.Tools;

var sqlConfig = new SQLServerConn(
    sqlserverName: "myserver",
    serverPort: 1433,
    authenticationType: AuthType.Windows,
    userName: null,
    password: null,
    connectionTimeOut: 30,
    appName: "MyApplication"
);

// Build connection string from config
string connectionString = sqlConfig.BuildConnectionString("MyDatabase");

Windows Impersonation (Windows Only)

using SolGrpUnltd.Tools;
using System.Security.Principal;

SafeAccessTokenHandle token = GetUserToken(); // Your token acquisition logic

int result = SQLData.rExecuteScaler_Int(
    connectionString,
    query,
    token,
    commandTimeout: 120
);

Handled SQL Error Codes

The library automatically retries operations when the following transient SQL Server errors occur:

• Connection Errors: Timeout expired, connection failures, network issues
• Resource Errors: Server too busy, insufficient resources
• Transactional Errors: Deadlocks, serialization failures, dependency failures
• Azure SQL Errors: Database unavailable, service busy, failover issues

See the _sqlExceptions array in the source code for the complete list of handled error codes.

Method Naming Convention

• Standard Methods: ExecuteScaler_Int, ExecuteScaler_String, etc.
• Resilient Methods: Prefixed with r (e.g., rExecuteScaler_Int) for automatic retry behavior

Dependencies

• Microsoft.Data.SqlClient: SQL Server database connectivity
• Microsoft.Extensions.Resilience: Resilience and retry patterns
• Polly: Resilience and transient fault handling library
• Azure.Identity: Azure authentication support
• SolGrpUnltd.Tools_Extensions: SGU internal extensions library

Best Practices

1. Use Resilient Methods: Prefer r-prefixed methods (e.g., rExecuteScaler_Int) for production scenarios to handle transient failures automatically
2. Connection Timeout: Set appropriate connection timeouts based on your network latency and query complexity
3. Parameterized Queries: Always use parameterized queries to prevent SQL injection (extend this library or use ADO.NET directly)
4. Dispose Connections: Use using statements when managing connections manually

Contributing

This is an internal SolGrpUnltd library. For contributions or issues, please contact the development team through Azure DevOps.

License

Proprietary - SolGrpUnltd

Support

For support, please contact the SolGrpUnltd development team or create an issue in the Azure DevOps repository.

Repository: SolGrpUnltd_Tools_TSQL
Version: 2026.217.1053