Creating a data access plugin

A database plugin can perform database operations against EvenCart database to extend default EvenCart software.

Before we create a database plugin, we need to create database versions for our plugin.

The following document describes procedure to create a Database plugin.

Creating the plugin class

A plugin class that inherits EvenCart.Services.Plugins.DatabasePlugin class becomes a database plugin class.

Within the plugin class, we'll need to tell EvenCart about our database versions. To do this, we'll need to override the method GetDatabaseVersions and return the list of database versions that our plugin has.

A database plugin class at the very minimum look like below.

using System.Collections.Generic;
using DotEntity.Versioning;
using EvenCart.Services.Plugins;
using EvenCart.Infrastructure;
using My.Plugin.Versions;

namespace My.Plugin
{
    public class MyDbPlugin : DatabasePlugin
    {
        public override IList<IDatabaseVersion> GetDatabaseVersions()
        {
            var versions = base.GetDatabaseVersions();
            versions.Add(new Version_1_0());
            return versions;
        }
    }
}

In the above example, a thing worth nothing is that the GetDatabaseVersion method first calls it's base class method. This is essential for a database plugin to work correctly.

Creating data access services

Creating data access services in EvenCart is very easy and follows generic inheritance and implementation to reduce the amount of code required to perform database operations.

EvenCart exposes a generic interface called EvenCart.Core.Services.IFoundationEntityService<T> and a generic abstract class EvenCart.Core.Services.FoundationEntityService<T> that implements the interface. The class FoundationEntityService<T> contains full implementation for all the methods. Thus any sub classes automatically implement the same methods.

In order to write data access services, two things are required.

1. An interface that inherits the interface IFoundationEntityService<T> with the actual domain entity class as it's generic type parameter. We can add more method signatures to this interface as per our requirements.
2. A class that inherits the class FoundationEntityService<T> with the actual domain entity class as it's generic type parameter and implements the interface created above in step 1.

For example if we need to create data access services for our entity called Book from our domain entities example, we'll have the following interface and classes.

Data Access Interface

using EvenCart.Core.Services;
using My.Plugin.Data;

namespace My.Plugin.Services
{
    public interface IBookService : IFoundationEntityService<Book>
    {

    }
}

Data Access Implementation

using EvenCart.Core.Services;
using My.Plugin.Data;

namespace My.Plugin.Services
{
    public class BookService : FoundationEntityService<Book>, IBookService
    {

    }
}

Note how we pass our domain entity Book as generic type parameter to both the constructs above.

Now we just need to register our service with the dependency container.

...
registrar.Register<IBookService, BookService>();
...

You can read more about dependency injection here. Our service interface IBookService will now be available for resolution within Controllers or anywhere else.

Data access methods

FoundationEntityService<T> implements the following methods.

As you can see, the methods are similar to those exposed by DotEntity.

Consuming the services

In order to consume the service we can inject the service interface into our controller (or manually resolve the interface as described here if you are working with the service outside the controller).

In the following example, we setup a controller, inject the IBookService and consume the service inside our action method.

public class BooksController : FoundationController
{
    private readonly IBookService _bookService;
    public BooksController(IBookService bookService)
    {
        _bookService = bookService;
    }

    public IActionResult Get(int id)
    {
        var book = _bookService.Get(id);
        return R.Success.With("book", book).Result;
    }
}

The above example fetches the Book with the provided id from the table MARKDOWN_HASHd553e76263385cbb18947c5069239b3bMARKDOWNHASH *(All the table names in EvenCart start with the prefix ec)*

Note however that the virtual property Pages inside book object will be null because the default service doesn't fetch the related entities automatically.

The next section summarizes how we can override default functionality to fetch the data from Page table.

Customizing the services

There are times when default implementations from FoundationService<T> are limiting your queries. Because all the methods are declared as virtual you can always override any of the above methods.

For example, in the BookService above, the default implementation of Get(id) will fetch the Book matching with the provided Id. It however doesn't populate the related entity Page.

To achieve that, we'll override the Get(id) method in our BookService to include a join.

using EvenCart.Core.Services;
using My.Plugin.Data;

namespace My.Plugin.Services
{
    public class BookService : FoundationEntityService<Book>, IBookService
    {
         public override Book Get(int id)
        {
            return Repository.Join<Page>("Id", "BookId", joinType: JoinType.LeftOuter)
                .Relate(RelationTypes.OneToMany<Book, Page>())
                .Where(x => x.Id == id)
                .SelectNested()
                .FirstOrDefault();
        }
    }
}

In the above example, we have provided a new implementation for Get(id) method that fetches linked Page rows. The relate function is used to define the relationship one-to-many from Book to Page.

Note that each Page object also automatically gets it's Book virtual property assigned.

The Repository in the above code is a wrapper around EntitySet<T> from DotEntity library.