Skip to content

Home

Jump to bottom
Eros Stein edited this page Apr 12, 2017 · 28 revisions

Welcome to the blayer wiki! Here you'll find detailed information on how to use the library.

Here's how to get started:

Add connection string

  • Since 1.0.21:

Just add any regular connection string, with the name of your choice.

  • Before 1.0.21:

You must create a connection string with the entry's name DbConnection. This will tell Blayer which database to connect to.

example

<connectionStrings>
    <add name="DbConnection" providerName="System.Data.SqlClient" connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=MyDatabase;Integrated Security=True;MultipleActiveResultSets=True" />
  </connectionStrings>

Project Structure

You only need one project to handle your domain interactions to work with Blayer.Data, but desirably you'd have the following structure:

  • Create 2 projects:

    1. Your.Namespace.Domain
    2. Your.Namespace.Poco

  • Add Blayer.Data to your domain project

Inside the domain project

Folders:

  1. AdditionalSteps
  2. ModelConfiguration
  3. Notifications
  4. Repositories
  5. Validations

A file in the root of the project named AppConfiguration (just an example) with the content:

namespace UserNamespace
{
    public class AppConfiguration : RepositoryConfiguration
    {
        public AppConfiguration()
        {
            // If not set, blayer will look for a connection string named "DbConnection"
            ConnectionString = "YourConnectionStringOrName";
        }
    }
}

This project should reference Blayer.Data and Your.Namespace.Poco (if you have that project).

Inside the POCO project

Just your regular POCO classes

Setting up the templates

VS 2017+

Pending

VS 2015 and older

Copy the folders under Blayer.Data/Templates to:

C:\Program Files (x86)\<your_vs_version>\Common7\IDE\ItemTemplates\CSharp\Blayer

Example:

C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\ItemTemplates\CSharp\Blayer

This will allow you to use the code templates provided to be used with Blayer.

Optional, but very likely you'll need to do it, step

It's very likely VS won't just reload and show you the new templates, so you might need to:

  1. Close all instances of Visual Studio.
  2. Delete the ItemTemplateCache folder inside C:\Program Files (x86)\<your_vs_version>\Common7\IDE
  3. On the Start menu, click Run, type cmd, and click OK.
  4. At the command prompt, locate the directory that contains devenv.exe, and type devenv /installvstemplates.
  5. Run devenv /setup.
  6. Run Visual Studio.

More information:

Explanation of the interfaces IAdditionalStep, IValidate and INotify

IAdditionalStep

Is used when we need to execute actions post validations. This is used for repetitive tasks that happen every time a record is created/updated and/or removed.

Example:

Let's say we need to change the date and time of the last operation in a record of type X. We create a class implementing IAdditionalStep and use the following code:

switch (state)
{
    // If the entity was added (data creation)
    case System.Data.Entity.EntityState.Added:
        {
            entity.LastAction = DateTime.Now;
        }
        break;
    // If the entity was removed (data removal)
    case System.Data.Entity.EntityState.Deleted:
        {

        }
        break;
    // If the entity was updated (data update)
    case System.Data.Entity.EntityState.Modified:
        {
            entity.LastAction = DateTime.Now;
        }
        break;
    default:
        break;
}

This way every time we add or update one of the records represented by this repository the property LastAction will be automatically updated.

IValidate

Is used when we need to validate the records. Exceptions thrown here will prevent the entity of having its data persisted. We might use different validations for every time a record is created/updated and/or removed.

Example:

Let's say we want to make sure:

  1. The user's name is longer than 4 characters
  2. The password is secure
  3. We're not removing an active user

For that, we create a class implementing IValidate, in this case a User class and use the following code:

switch (state)
{
    // If the entity was added (data creation)
    case System.Data.Entity.EntityState.Added:
        {
            if(string.IsNullOrWhiteSpace(entity.Name) || entity.Name.Length <= 4)
                throw new BusinessException("Please inform a valid name.");

            if(!Tools.IsPasswordSecure(entity.Password))
                throw new BusinessException("Please inform a secure password.");
        }
        break;
    // If the entity was removed (data removal)
    case System.Data.Entity.EntityState.Deleted:
        {
            if(entity.IsActive)
                throw new BusinessException("Active users can't be removed.");
        }
        break;
    // If the entity was updated (data update)
    case System.Data.Entity.EntityState.Modified:
        {
            if(entity.Name != dbEntity.Name && (string.IsNullOrWhiteSpace(entity.Name) || entity.Name.Length <= 4))
                throw new BusinessException("Please inform a valid name.");

            if(!string.IsNullOrWhiteSpace(entity.Password) && !Tools.IsPasswordSecure(entity.Password))
                throw new BusinessException("Please inform a secure password.");
        }
        break;
    default:
        break;
}

INotify

Is used when we need to execute actions after the entity has been persisted to the database. This is used for repetitive tasks that happen every time a record is successfully created/updated and/or removed.

Example:

Let's say we need to notify by email the administrator(s) every time a record of type X is removed. We create a class implementing INotify and use the following code:

switch (state)
{
    // If the entity was added (data creation)
    case System.Data.Entity.EntityState.Added:
        {

        }
        break;
    // If the entity was removed (data removal)
    case System.Data.Entity.EntityState.Deleted:
        {
            Tools.SendEmailToAdministrators(
                $"Record {entity.Name} has been removed by {((User)ctx.LoggedUser).Name}");
        }
        break;
    // If the entity was updated (data update)
    case System.Data.Entity.EntityState.Modified:
        {

        }
        break;
    default:
        break;
}

This way every time we remove a record of type X the administrator(s) will be notified by email.

Every class implementing any of those interfaces will have a method with a switch inside. Depending on the state of the record a specific section is hit. The properties are as informed below:

  • System.Data.Entity.EntityState state: Entity's current state - state of the record. If it is being created, modified or deleted.
  • object entityObject: Entity - the entity that is currently being processed.
  • object originalEntity: Unmodified entity - the original entity as it is in the database at the moment of this execution. This property is only present when the state is modified.
Clone this wiki locally