Sytadelle.Systems.Entities 1.0.0-alpha

Sytadelle.Systems

Sytadelle Systems est un système de base pour commencer un projet en .net. Il est composé de quatre parties : Entities, Data, Services et Api. Ces packages s'imbriquant entre eux (le package Entities est utilisé dans Data, Data est utilisé dans Services et Services est utilisé dans Api) :

1. Dans Entities vous retrouverez les modèles de données de base pour chacune de vos entités.
2. Ces entités seront accessibles en lecture et écriture via Data.
3. La gestion des droits et de sécurité concernant la modification et l'ajout d'entités se fait dans Services.
4. Enfin les endpoints sont définis dans Api via des controllers

On va présenter chacune de ces parties pour voir en quoi elles peuvent vous aider et comment vous pouvez les utilisez dans vos projets.

Sytadelle.Systems.Entities

Ce package utilise le code first avec SQLServer, dedans on y définit le modèle de donnée de base qui se nomme BaseEntity :

namespace Sytadelle.Systems.Entities
{
   public abstract class BaseEntity
   {
       public long Id { get; set; }
       public Guid Guid { get; set; } = Guid.NewGuid();
   }
}

Dans un premier temps toutes vos entités pourront hériter de cette classe.

Il y a un modèle de donnée pour l'entité qui jouera le rôle de gestion des droits dans le package Services : le BaseTenantEntity (il hérite de BaseEntity).

namespace Sytadelle.Systems.Entities
{
   public abstract class BaseTenantEntity<T> : BaseEntity
       where T : BaseEntity
   {
       // tenant is the owner of the row, can be an organization
       public T? Tenant { get; set; }

       public DateTime? CreatedAt { get; set; }
       public DateTime? ReadAt { get; set; }
       public DateTime? UpdatedAt { get; set; }
       public DateTime? DeletedAt { get; set; }
       public DateTime? EnabledAt { get; set; }
   }
}

Un BaseTenantEntity est une entité qui va cloisonner une ou plusieurs autres entités. Ainsi on sécurise certaines données en n'acceptant des modifications ou des suppressions sur celles-ci uniquement si leur tenant est le même que l'entité connecté qui sera du type BaseUser.

namespace Sytadelle.Systems.Entities
{
   public abstract class BaseUser<T> : BaseTenantEntity<T>
       where T : BaseEntity
   {
       public Role Role { get; set; }
   }
}

Prenons l'exemple d'une application de blog où l'on retrouve des users, des profiles et des postes. Le profile possédera plusieurs postes et il sera le seul à pouvoir modifier ou supprimer ses propres postes. Mais un profile est connecté à un User et c'est le user qui fera le pont entre le poste et le profile. Ainsi nous avons le profile qui est un Tenant, le poste qui est un BaseTenantEntity et le User qui est un BaseUser. Si lors d'une modification le user a le même tenant que le poste (et donc le même profile) alors la modification sera accordée.

Il est à noter qu'un BaseUser a un rôle et que cela peut déterminer ce qu'il pourra faire ou non sur la donnée. On peut notamment gérer ça grâce à l'entité Permission.

namespace Sytadelle.Systems.Entities.Permissions
{
   public class Permission : BaseEntity
   {
       public string Name { get; set; }

       /// <summary>
       /// pattern : * or specific entity name
       /// </summary>
       public string Entity { get; set; }

       public int Priority { get; set; }

       public bool Create { get; set; }
       public bool Read { get; set; }
       public bool Update { get; set; }
       public bool Delete { get; set; }

       // compare with user role to determine the user permission over the specific entity
       public Role Role { get; set; }
   }
}

L'entité Permission permet de définir pour chaque entité différentes permissions en fonction des rôles des BaseUser. Si l'on reprend l'exemple du blog mais en rajoutant une nuance : plusieurs users peuvent accéder au même profile mais avec des rôles différents. Dans ce cas certains users seront admin tandis que d'autres seront de simple user, les admins pourront modifier, ajouter ou supprimer des données tandis que les simple users ne pourront que les voirs.

Sytadelle.Systems.Data

On définit dans ce package un système de repository : la classe BaseRepository ainsi que son interface IBaseRepository contiennent diverses fonctions qui permettent de modifier une entité.

namespace Sytadelle.Systems.Data
{
   public interface IBaseRepository<TEntity> : IDisposable where TEntity : BaseEntity
   {
       IQueryable<TEntity> Query(Expression<Func<TEntity, bool>>? predicate = null, long? tenantId = null, bool tracking = true, bool? enabled = true);
       IQueryable<TEntity> DynamicQuery(string q, string order, long? tenantId, bool? enabled = true);

       TEntity? GetById(long id);
       TEntity? GetById(Guid guid);

       void Add(TEntity entity);
       void Delete(TEntity entity);
       void Update(TEntity entity);

       bool NavigationsHaveSameTenantId(TEntity entity, long? tenantId);

       int SaveChanges();
   }
}

Dans le cas où vous utilisez un tenant vous pourrez utiliser certaines méthodes du BaseRepository dans vos services. Il y a Notamment la méthode "NavigationsHaveSameTenantId" qui permet de vérifier que toutes les attributs de type entité d'entité ont bien le même tenant. On ne pourra pas, par exemple, ajouter un poste sur un profile (ici notre tenant) qui n'est pas lié à l'utilisateur puisque l'utilisateur doit être lié au même profile que notre poste.

public bool NavigationsHaveSameTenantId(TEntity entity, long? tenantId)
{
   if (tenantId == null)
   {
       return true;
   }

   var navigationProperties = DbContext.Model
       .FindEntityType(typeof(TEntity))
       .GetNavigations()
       .Where(x => !x.IsCollection && x.PropertyInfo.Name != "Tenant")
       .ToList();

   ...
}

Un système de pagination, en dehors du BaseRepository, est également présent dans le package mais n'est utilisé que dans le package du Services. Vous pouvez cependant override les fonctions du BaseRepository pour inclure la pagination.

namespace Sytadelle.Systems.Data
{
    public class PagedList<T> : List<T> where T : BaseEntity
    {
        public const int DefaultSize = 25;

        public int TotalPages { get; set; }
        public int CurrentPage { get; set; }
        public int TotalCount { get; set; }

        public PagedList(List<T> items, int pageNumber, int pageSize, int count)
        {
            CurrentPage = pageNumber;
            TotalCount = count;
            TotalPages = (int)Math.Ceiling((double)count / pageSize);
            AddRange(items);
        }

        public static async Task<PagedList<T>> GetByPageAsync(IQueryable<T> query, int pageNumber, int pageSize)
        {
            var count = await query.CountAsync();

            if (pageNumber <= 0)
            {
                pageNumber = 1;
            }

            if (pageSize <= 0 || pageSize > DefaultSize)
            {
                pageSize = DefaultSize;
            }

            var results = await query.Skip(pageSize * (pageNumber - 1))
                                     .Take(pageSize)
                                     .ToListAsync();

            return new PagedList<T>(results, pageNumber, pageSize, count);
        }
    }
}

Sytadelle.Systems.Services

Ce package définit un système de sécurité de base (en lien avec les permissions et les tenants qu'on a vu juste avant). On va y faire des vérifications concernant l'utilisateur connecté (si celui est null alors il n'y aura pas de vérification).

La pagination est réalisée au sein de ce package.

Built With

• ASP.NET Core
• EntityFramework Core
• Dynamic Linq

Getting Started

Sytadelle.Systems.Api is a basic system to start a project in .net. The goal is to start quickly and easily a .net project with this package. In fact many basics implementations are already done (like the pagination or some basics security for your data). So with Sytadelle.Systems.Api you will easily create an API which can implement CRUD on all data of your app. You can also use it for differents needs and it is easily adaptable.

It is important to notice that Sytadelle.Systems.Api used three others Sytadelle packages : Entities, Data, Services. These packages intertwining with each other (the Entities package is used in Data, Data is used in Services and Services is used in Api) :

1. In the Entities package you will find basics data models for each of your entities.
2. We can read and write theses entities with the Data package.
3. The management of the rights and security about the modification and the addition of entities is made in Services package.
4. The endpoints are defined in Api package with controllers

In resume : You can call endpoints to get or modify your data, the endpoint will call the service (Api package) ⇒ The service will verify if we have the rights for the request, if it is the case the service will call repository (Services) ⇒ The repository will return or modify the data requested (Data). The data has the form you gave it in entities

Now, for this first tutorial, we will create a basic application using Sytadelle.Systems.Api:

Prerequisites

Open Visual Studio (install it if you don't have it, https://visualstudio.microsoft.com/downloads/ ). ⇒ We use Visual Studio because it's the better IDE to code a .net project.

Installation

1. Create a new project ASP.NET Core Web API using .net6
2. Delete WeatherForecast.cs file and the file WeatherForecastController.cs which is in Controllers folder
3. Go in manage nuget packages and install Sytadelle.Systems.Api ⇒ You will access, through Sytadelle.Systems.Api, to the packages Sytadelle.Systems.Entities, Sytadelle.Systems.Data and Sytadelle.Systems.Services.
4. Install the package "Microsoft.EntityFrameworkCore.Tools" too, we will need it to run some commands to update our database with our models

Usage

A sample project can be found in the folder Sytadelle.Systems.Samples.EFCore which use basically the sytadelle entities, data framework to build a code first SQL Server application. More samples come later.

Roadmap

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the Sytadelle License. See LICENSE.txt for more information.

Contact

contact@sytadelle.fr