Catch.Catcher 0.1.11

<p align="center"> <img width="192" height="192" src="catcherlogo.png"/> </p>

Catcher

CosmosDB Based with MongoDB Interface, with generic DAO Design Pattern for .NET Framework with C# Language.

We're sorry that version before 0.1.4 are have many API changes through the version. After 0.1.4, there will be consistency in the framework API.

Changelog

for changelog check here

Features

• Factory pattern
• Automatic query generator
• Automatic Dao creator
• Can search most similiar(not necessary equal) object
• Automatic connection creator
• Using attributes to exposed metadata

Requirements

• .NET standard 1.5 and higher

Installation

Visual Studio NuGet Package Manager

You can use default NuGet Package Manager in visual studio and search "Catch.Cather" and install it, as easy as that.
Don't forget to resolve double dependency if you have one.

Package Manager

Execute this line in your package manager terminal inside your project :

Install-Package Catch.Catcher -Version 0.1.9

.NET CLI

Execute this line in your .NET CLI inside your project :

dotnet add package Catch.Catcher --version 0.1.9

Manually

1. Clone this repository.
2. Added to your project.
3. Congratulation!

Usage example

Initialize Framework

You need to inject your config once before you can use this framework.

1. Create Configuration Provider.

using Catcher.DB.DAO;

namespace YourNameSpace
{
    public class ConfigurationProvider : IConfigurationProvider
    {
        public string DBName => "YOUR_DB_NAME";

        public string DBHost => "www.your.db.host.com";

        public int DBPort => 1234;

        //insert DBUserName and DBPassword null if your db don't have credential
        public string DBUserName => "yourUserName";
        
        public string DBPassword => "y0UR_p4$sW0Rd";

        public bool IsUseSsl => true;

    }
}

2. Inject Your Configuration Provider.

//this context will stored your configuration as long as your program run
DaoConfigurationContext.Provider = new ConfigurationProvider();

Create Dto

All you need to do is create model class which extends our Dto abstract class and put DtoClass Attribute above your class.
Keep in mind that Dto is using Bson library from mongoDB, so you can manipulate field name using BsonElement attribute.
Don't forget to add "?" at primitive property (int, float, double, long, bool, decimal) so its default value is null.

using Catcher.DB.DTO;

namespace YourProject.Model
{
    [DtoClass("NAME_OF_YOUR_DB", "NAME_OF_YOUR_COLLECTION")]
    public class Tag : Dto
    {   
        public string TagName { get; set; }

        public int? View { get; set; }
    }
}

If your model have unique field other than default object id, then you can put DtoUniqueField attribute on your property.
The acceptable type for unique field type is : string, int, MongoDBRef(Or Dto with ObjectRef attribute), ObjectId.
Remember, this field should not be null when you want to insert it to the database.
You can have more than one unique field.

using Catcher.DB.DTO;

namespace YourProject.Model
{
    [DtoClass("NAME_OF_YOUR_DB", "NAME_OF_YOUR_COLLECTION")]
    public class User : Dto
    {   
        [DtoUniqueField]
        public string UserName { get; set; }

        public string Password { get; set; }
    }
}

If your model have composite id just put DtoCompositeField attribute on your property.
Obviously, minimum number of composite property is two.
The acceptable type for composite field type is : string, int, MongoDBRef(Or Dto with ObjectRef attribute), ObjectId.
Remember, this field should not be null when you want to insert it to the database.

using Catcher.DB.DTO;

namespace YourProject.Model
{
    [DtoClass("NAME_OF_YOUR_DB", "NAME_OF_YOUR_COLLECTION")]
    public class Item : Dto
    {   
        [DtoCompositeField]
        public MongoDBRef user { get; set; }

        [DtoCompositeField]
        public string itemName { get; set; }
    }
}

If your model have MongoDBRef and you want it to auto connect with the related Dto class, you can use BsonSerializer Attribute and pass the type of DBRef attribute.
Keep in mind that this method will multiply time of your query because its actually do extra query to fetch MongoDBRef into the object especially when the object is not exist in the cache.
There is two type of object ref :

• ObjectRef<T> for single MongoDBRef
• ListObjectRef<T> for list of MongoDBRef
  T must be Dto and must be the same type as its attributed property
  Remember, query using this field as parameter will convert the object into MongoDBRef and will ignore any Dto field.

using Catcher.DB.DTO;

namespace YourProject.Model
{
    [DtoClass("NAME_OF_YOUR_DB", "NAME_OF_YOUR_COLLECTION")]
    public class Item : Dto
    {   
        [DtoCompositeField]
		[BsonSerializer(typeof(ObjectRef<User>))]
        public User user { get; set; }

        [DtoCompositeField]
        public string itemName { get; set; }
    }
}

If your model have different connection than default ConfigurationProvider, you can add DtoCustomConnection attribute to the Dto class

namespace YourProject.Model
{
    [DtoClass("NAME_OF_YOUR_DB", "NAME_OF_YOUR_COLLECTION")]
	[DtoCustomConnection("www.yourhost.com", 1234, "NAME_OF_YOUR_DB")]
    public class User : Dto
    {   
        [DtoUniqueField]
        public string UserName { get; set; }

        public string Password { get; set; }
    }
}

What Dto can do

//Dto at default have getter setter for ID
ObjectId id = user.ID;

//Dto can fetch itself to update the object to newer version from the database
user.Fetch<User>();

//get MongoDBRef to user
MongoDBRef ref = user.ToDBRef<User>();

//get object from MongoDBRef
User userFromRef = ref.Retrieve<User>();

//update object from the database
Dto.Fetch(userFromRef);

Get Dao

To get Dao for your specific Dto, you can get it from DaoContext class. It will only create one Dao object for every Dto class and reuse it.

//import this namespace
using Catcher.DB.DAO;

IDao<User> dao = DaoContext.GetDao<User>();

Using Dao

Here are some of Dao can do :

//inserting. Any null property will be ignored. If there is object in the database with same ObjectId/UniqueId/CompositeId, then it will return false and abandon the insert task, otherwise it will return true.
var isSuccess = dao.Insert(user);

//Deleting user. It will search by its objectId first and unique id / composite id if you did not provide one
dao.Delete(user);

Find using Dao

Here are some of method to find object in the database :

//Find by object id
User user = dao.Find.ByObjectID(id);

//Find object that looks like (not necessary equal) your object
IList<User> usersLike = dao.Find.WhenLike(user);

//Find object that equal with your object (except its ObjectId and unique field name) and ignore it's null property
IList<User> usersLike = dao.Find.WhenEqual(user, true);

Create Rollback Action

The framework contains method to create sequence of query task which will automatically rollback if failed in the middle of query
If the rollback is failed, then it will try to rollback again after the given interval and times
If the rollback still faild, it will create Trace error with information about the query its try to rollback so you can rollback it manually later

//Create rollbacker object which will rollback every 5 minutes if failed for 3 times
var rollbacker = new Rollbacker(5, 3);
rollbacker.AddInsertTask(object1);
rollbacker.AddDeleteTask(object2);
rollbacker.Execute();

Contribute

We would love you for the contribution to Catcher, just contact me to nayanda@catch.co.id