Terminalogic.Essentialsvb 1.0.0

Terminalogic.Essentials

A lightweight VB.NET data-access library for SQL Server that removes the boilerplate from everyday database operations. Built on top of Microsoft.Data.SqlClient, it provides a clean, minimal API for reading and writing data using either raw SQL or stored procedures.

Requirements

• .NET 8.0 or later
• SQL Server (any edition)
• A ConnectionString entry in your application's configuration file (see Setup)

Setup

1. Install the package

dotnet add package Terminalogic.Essentials

2. Configure your connection string

Add a ConnectionString entry to your App.config or Web.config:

<configuration>
  <connectionStrings>
	<add name="ConnectionString"
		 connectionString="Server=YOUR_SERVER;Database=YOUR_DB;Integrated Security=True;TrustServerCertificate=True;" />
  </connectionStrings>
</configuration>

Note: The key must be named exactly ConnectionString. The _data class reads this name by convention.

3. Instantiate the class

Dim db As New _data()

API Reference

All methods accept an optional ParamArray parameters() As Object argument for passing SQL parameters as flat name/value pairs:

"@paramName", value, "@paramName2", value2, ...

The leading @ is optional — it will be added automatically if omitted.

read — Execute a SELECT query

Returns a DataTable with the results of a raw SQL SELECT statement.

Function read(sql As String, ParamArray parameters() As Object) As DataTable

Example — no parameters:

Dim dt As DataTable = db.read("SELECT * FROM Products")

Example — named parameters:

Dim dt As DataTable = db.read(
	"SELECT * FROM Products WHERE CategoryId = @cat AND Active = @active",
	"@cat", 3,
	"@active", True)

Example — positional parameters (use "?" as the name):

Dim dt As DataTable = db.read(
	"SELECT * FROM Products WHERE CategoryId = ? AND Active = ?",
	"?", 3,
	"?", True)

Positional "?" placeholders are replaced left-to-right with auto-generated names @p0, @p1, etc.

readx — Execute a SELECT stored procedure

Returns a DataTable from a stored procedure that returns a result set.

Function readx(storedProcedure As String, ParamArray parameters() As Object) As DataTable

Example:

Dim dt As DataTable = db.readx("usp_GetProductsByCategory", "@cat", 3)

search — LIKE search query

Identical to read, but automatically wraps every string parameter value with % wildcards, making it ideal for LIKE-based searches.

Function search(sql As String, ParamArray parameters() As Object) As DataTable

Example:

Dim dt As DataTable = db.search(
	"SELECT * FROM Products WHERE Name LIKE @name",
	"@name", "widget")
' Executes: ... WHERE Name LIKE '%widget%'

Only String values are wrapped with wildcards. Numeric and other typed values are passed through unchanged.

write — Execute a non-query SQL statement

Executes an INSERT, UPDATE, DELETE, or any other non-query SQL statement. Returns nothing.

Sub write(sql As String, ParamArray parameters() As Object)

Example — INSERT:

db.write(
	"INSERT INTO Products (Name, Price, CategoryId) VALUES (@name, @price, @cat)",
	"@name", "Widget Pro",
	"@price", 19.99D,
	"@cat", 3)

Example — UPDATE:

db.write(
	"UPDATE Products SET Price = @price WHERE Id = @id",
	"@price", 24.99D,
	"@id", 42)

Example — DELETE:

db.write("DELETE FROM Products WHERE Id = @id", "@id", 42)

writex — Execute a non-query stored procedure

Executes a stored procedure that performs writes (INSERT/UPDATE/DELETE). Returns nothing.

Sub writex(storedProcedure As String, ParamArray parameters() As Object)

Example:

db.writex("usp_ArchiveProduct", "@id", 42, "@archivedBy", "admin")

Parameters: Named vs. Positional

Both styles can be used with any of the five methods.

Handling NULL

Pass Nothing as a parameter value — it will be automatically converted to DBNull.Value:

db.write(
	"UPDATE Products SET DiscontinuedDate = @date WHERE Id = @id",
	"@date", Nothing,
	"@id", 42)

Iterating Results

All read, readx, and search methods return a standard DataTable:

Dim dt As DataTable = db.read("SELECT Id, Name, Price FROM Products")

For Each row As DataRow In dt.Rows
	Console.WriteLine($"{row("Id")}: {row("Name")} — ${row("Price")}")
Next

Dependencies

License

This project is licensed under the MIT License.