NiORM 1.4.0

NiORM

NiORM is a lightweight Object-Relational Mapper (ORM) for .NET, designed to simplify interactions with SQL databases. It uses a convention-over-configuration approach, enabling developers to map C# classes to database tables using attributes. NiORM offers an intuitive interface for querying and manipulating data with minimal overhead.

Features

• Attribute-based Mapping: Use [TableName], [PrimaryKey], and other annotations to define the schema directly in your C# classes.
• Entity Management: Create, retrieve, update, and delete records easily through Entities<T> collections.
• Query Simplification: Chain LINQ-style queries for simple and advanced data filtering.
• Raw SQL Execution: Execute raw SQL queries when needed, returning mapped objects.
• Multiple Database Support: Handle multiple databases within the same project.
• 🆕 Comprehensive Error Handling: Custom exception classes for better error identification and handling.
• 🆕 Built-in Logging System: Configurable logging with multiple levels and output options.
• 🆕 Enhanced XML Documentation: Complete IntelliSense support with detailed examples and exception documentation.

Installation

Download & Install the nuget using:

Nuget Package Manager:

NuGet\Install-Package NiORM -Version

.Net CLI:

dotnet add package NiORM

Quick Start

Here’s how you can get started with NiORM in your application:

1. Define a Model:

Use attributes like [TableName] and [PrimaryKey] to map a C# class to a database table.

using NiORM.Attributes;
using NiORM.SQLServer.Interfaces;

[TableName("People")]
public class Person : ITable
{
    [PrimaryKey(isAutoIncremental: true)]
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}

2. Set up a Data Service:

Create a service class that inherits from DataCore. This class will act as the interface between your application and the database.

using NiORM.SQLServer;
using NiORM.Test.Models;

public class DataService : DataCore
{
    public DataService(string connectionString) : base(connectionString) { }

    public IEntities<Person> People => CreateEntity<Person>();
}

3. Interact with the Database:

Use the data service to fetch, insert, update, and delete records.

var dataService = new DataService("your-connection-string-here");

// Fetch all people
var people = dataService.People.ToList();

// Add a new person
var newPerson = new Person() { Age = 29, Name = "Nima" };
dataService.People.Add(newPerson);

// Query with conditions
var filteredPeople = dataService.People.Where(p => p.Name == "Nima").ToList();

4. Execute Raw SQL (when necessary):

If you need more control, you can execute raw SQL queries and map them to your models.

var cats = dataService.SqlRaw<Cat>("SELECT * FROM Cats");

or

var names = dataService.SqlRaw<string>("SELECT [Name] FROM Cats");

🆕 Error Handling and Logging

NiORM now includes comprehensive error handling and logging capabilities:

Enable Logging:

using NiORM.SQLServer.Core;

// Enable logging to console
NiORMLogger.IsEnabled = true;
NiORMLogger.MinimumLogLevel = LogLevel.Info;

// Or log to file
NiORMLogger.LogFilePath = @"C:\logs\niorm.log";

Enhanced Error Handling:

try
{
    var person = dataService.People.Find(123);
}
catch (NiORMValidationException ex)
{
    // Handle validation errors
    Console.WriteLine($"Validation error: {ex.Message}");
}
catch (NiORMConnectionException ex)
{
    // Handle connection issues
    Console.WriteLine($"Connection failed: {ex.Message}");
}
catch (NiORMException ex)
{
    // Handle other NiORM errors
    Console.WriteLine($"Database error: {ex.Message}");
    if (!string.IsNullOrEmpty(ex.SqlQuery))
    {
        Console.WriteLine($"Failed query: {ex.SqlQuery}");
    }
}

Safe Operations with Enhanced Service:

public class SafeDataService : DataCore
{
    public SafeDataService(string connectionString) : base(connectionString)
    {
        // Configure logging
        NiORMLogger.IsEnabled = true;
        NiORMLogger.MinimumLogLevel = LogLevel.Warning;
    }

    public bool TryAddPerson(Person person, out string errorMessage)
    {
        errorMessage = string.Empty;
        try
        {
            People.Add(person);
            return true;
        }
        catch (NiORMException ex)
        {
            errorMessage = ex.Message;
            return false;
        }
    }

    public IEntities<Person> People => CreateEntity<Person>();
}

📖 For detailed documentation, see: Error Handling and Logging Guide

Contributing

We welcome contributions! Please fork the repository and submit pull requests for any improvements or features you'd like to add.

License

This project is licensed under the MIT License.