Terminalogic.Essentials.Legacy 1.0.0

TerminalogicEssentialsLegacy

A lightweight VB.NET data-access library for SQL Server targeting .NET Framework 4.8. It removes the boilerplate from everyday database operations by providing a clean, minimal API for reading and writing data using either raw SQL or stored procedures. Built on top of System.Data.SqlClient.

Looking for the modern .NET 8+ version? See Terminalogic.Essentials.

Requirements

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

Setup

1. Install the package

Install-Package TerminalogicEssentialsLegacy

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;" />
  </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 four 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.