SavantBuffer.DbConnector 1.6.0

.NET Standard 2.0
dotnet add package SavantBuffer.DbConnector --version 1.6.0
NuGet\Install-Package SavantBuffer.DbConnector -Version 1.6.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SavantBuffer.DbConnector" Version="1.6.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SavantBuffer.DbConnector --version 1.6.0
#r "nuget: SavantBuffer.DbConnector, 1.6.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install SavantBuffer.DbConnector as a Cake Addin
#addin nuget:?package=SavantBuffer.DbConnector&version=1.6.0

// Install SavantBuffer.DbConnector as a Cake Tool
#tool nuget:?package=SavantBuffer.DbConnector&version=1.6.0

DbConnector

A performance-driven and ADO.NET data provider-agnostic ORM library for .NET

đź‘ŤTip
Please visit https://www.savantbuffer.com for the complete documentation!

Introduction

What is a DbConnector?

DbConnector is a performance-driven and ADO.NET data provider-agnostic ORM library for .NET developed for individuals who strive to deliver high-quality software solutions. Object-Relational Mapping (ORM) is a technique that lets you query and manipulate data from a database using an object-oriented paradigm. This highly efficient library helps with the task of projecting/mapping data from any database, with the support of any third party data provider, into .NET objects and is comparable to the use of raw ADO.NET data reader implementations.

Why use SavantBuffer's DbConnector?

The purpose of this library is not to replace the Entity Framework since it can be very useful in certain scenarios.   It's for those who prefer to write SQL queries with optimal performance in mind. Some might say writing plain-text SQL queries is easier to understand and debug than using LINQ or .NET’s query syntax. Maybe someone in your team tends to lean towards a "stored procedure only" architecture? You might also be migrating your old Data Access Layer code into a more “modern” framework (e.g. .NET MVC). If you can relate to one of the mentioned, you’ll be happy to use this library. This documentation will further serve as guidance while providing examples on how to tackle these situations and more.

How fast is DbConnector?

It's extremely fast and memory efficient! Check out the Performance section for more details.

Requirements

Before we start, this documentation assumes you have knowledge on the following:

  • C# 6.0 or later (other .NET languages are supported but examples will not be provided in this documentation)
  • .NET Framework 4.5 or later (or .NET Core 1.0 or later)
  • SQL
  • Visual Studio 2017 or later
  • NuGet packages
  • One or more ADO.NET data-providers (e.g. SqlClient, Npgsql, etc.)

These topics are important for you to know since this library was developed leveraging the latest built-in .NET features. To name a few, some of these features are lambda delegates, the task-based async model, and value tuples.

Installation

DbConnector is installed via Visual Studio's NuGet package manager: https://www.nuget.org/packages/SavantBuffer.DbConnector

PM> Install-Package SavantBuffer.DbConnector

⚠️Warning
.NET Standard 2.0 and its implementations are only supported.

Getting Started

DbConnector Instance

Once you've downloaded and/or included the package into your .NET project, you have to reference the DbConnector and your preferred ADO.NET data provider namespaces in your code:

using DbConnector.Core;
using System.Data.SqlClient; //Using SqlClient in this example.

Now, we can create an instance of the DbConnector using the targeted DbConnection type:

//Note: You can use any type of data provider adapter that implements a DbConnection.
//E.g. PostgreSQL, Oracle, MySql, SQL Server

//Example using SQL Server connection
DbConnector<SqlConnection> _dbConnector = new DbConnector<SqlConnection>("connection string goes here");

đź‘ŤTip
DbConnector instances should be used as a singleton for optimal performance.

Main Functions

There are multiple functions available depending on your goals. The ones for reading data start with the word “Read” and “Non” for non-queries. For a better understanding, the IDbCommand Interface method naming convention was followed for all the functions. This was decided in order to assist in the migration of raw data provider code into DbConnector’s design pattern.

The following are the main generic functions:
  • Read
  • ReadAsAsyncEnumerable (v1.6.0)
  • ReadFirst
  • ReadFirstOrDefault
  • ReadSingle
  • ReadSingleOrDefault
  • ReadToList
  • ReadToDataTable
  • ReadToDataSet
  • ReadToKeyValuePairs
  • ReadToDictionaries
  • ReadToListOfKeyValuePairs
  • ReadToListOfDictionaries
  • NonQuery
  • NonQueries
  • Scalar
  • Build
Basic Example

Let’s say we have an “Employee” class serving as a container for the data we want to fetch from the database. The following function example shows how to synchronously load data from a database entity called “Employees” into an object of type List<Employee>:

public List<Employee> GetAll()
{
    return _dbConnector.ReadToList<Employee>(
        onInit: (cmd) =>
        {
            cmd.CommandText = "SELECT * FROM Employees";

        }).Execute();
}

public List<Employee> GetAllSimple()
{
    //v1.1 Allows the use of simpler overloads:
    return _dbConnector.ReadToList<Employee>("SELECT * FROM Employees").Execute();
}
What happened here?

The DbConnector was used to call the ReadToList function with the use of an “Employee” generic type. This function is requesting an Action<IDbJobCommand> delegate to be declared which is being explicitly provided by the use of the “onInit” named parameter. Inside this delegate, the IDbJobCommand argument object is then used to set the text command to run against the data source.

Noticed how a property called “CommandText” was set? This is because the IDbCommand Interface naming convention is being followed like previously mentioned.

Lastly, a function called Execute was called. A functional design pattern is being used and, consequently, an IDbJob object is being returned. This pattern allows for a lot of flexibility and you'll learn more in the following sections.

More Documentation

Please visit https://www.savantbuffer.com for the complete documentation!

Examples and Tests

Release Notes

Please see DbConnector’s CHANGELOG for details.

Known-Issues

Issues can be reported via DbConnector’s GitHub Issues feature.

Pending Features

New feature requests can be submited using DbConnector’s GitHub repo.

License

📢Notice
Copyright 2019 Robert Orama
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at <br><br>http://www.apache.org/licenses/LICENSE-2.0<br><br> Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contact

Hello, <br> My name is Robert Orama and I'm the author of the DbConnector library. As a computer engineer and software enthusiast, my goal is to share knowledge by means of this project. I hope the use of DbConnector is taken into serious consideration and can help provide efficient results for any type of .NET solution.<br><br>You can reach me via email if really necessary: rorama@savantbuffer.com<br><br>Don’t forget to donate<br><br>Thank you for your support!

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on SavantBuffer.DbConnector:

Repository Stars
TortugaResearch/DotNet-ORM-Cookbook
This repository is meant to show how to perform common tasks using C# with variety of ORMs.
Version Downloads Last updated
1.6.0 1,292 10/27/2022
1.5.0 1,096 7/20/2021
1.4.0 497 9/22/2020
1.3.0 460 6/12/2020
1.2.1 432 6/3/2020
1.2.0 399 5/26/2020
1.1.2 428 4/29/2020
1.1.1 462 11/20/2019
1.0.0 528 11/7/2019

Please visit https://www.savantbuffer.com/ for documentation!