DEV Community: Andrew

Design Patterns — Visitor in .NET

Andrew — Tue, 08 Mar 2022 17:25:46 +0000

We`ll revise what this pattern is about with some examples in .NET how it makes code more readable and adheres to some of the SOLID principles.

What is a Visitor, and what kind of problem does it solve?

The visitor is a behavioral design pattern that lets you separate algorithms from the objects on which they operate.

Assume that you are working on an API endpoint that accepts a set of entities. Each entity belongs to a hierarchy with a common ancestor, and your endpoint should validate these entities by different validation rules.

Here you can apply visitor, and it`ll play perfectly.

Let`s look at the wrong solutions for such tasks before the visitor comes into our code:

`cs
public class Resource { }

public class Storage : Resource { }

public class Compute : Resource { }

public class Validator
{
public void Validate(List resources)
{
foreach (var resource in resources)
{
if (resource is Storage)
{
Validate(resource as Storage);
}

        if (resource is Compute)
        {
            Validate(resource as Compute);
        }

        //pattern
        //if(resource is Type){
        // Validate( resource as Type);
        //}

    }
}

public void Validate(Storage storage)
{
}

public void Validate(Compute compute)
{
}

}
`

You see that when we add a new type, we also need to update the validator with a proper if block to validate the new type.

This approach violates the OpenClose principle because the code is not close for modifications with new conditions. In order to make it better, we can use the Visitor pattern here.

Take a moment to read about the OpenClose principle.

Take a look at the new code where we implement visitor design pattern:

`cs
public abstract class Resource
{
public abstract void Validate(Validator validator);
}

public class Storage : Resource
{
public override void Validate(Validator validator)
{
validator.Validate(this);
}
}

public class Compute : Resource
{
public override void Validate(Validator validator)
{
validator.Validate(this);
}
}

public class Validator
{
public void Validate(List resources)
{
foreach (var resource in resources)
{
resource.Validate(this);
}
}

public void Validate(Storage storage)
{
}

public void Validate(Compute compute)
{
}

}
`

Now validator relies on resource contracts. It should have a method validate which accepts a validator instance, and each type knows the proper method for self-validation.

In the future, when we add a new type, we don`t have to change something inside the validator. It means that the validator adheres OpenClose principle and can validate new types which any changes.

Conclusion

You get a simple but quite powerful pattern as a visitor to make your code shine. If you didn`t use visitor before in your code, I would suggest you check your existing code, and maybe you can improve the quality of it.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

ASP.NET Best Way to Store Secrets

Andrew — Wed, 23 Feb 2022 11:56:16 +0000

All over the development world, we use configuration files to store important values for our applications. Values differ from each other, and some require to be stored in a secure way. Such as database credentials or AUTH secrets.

Introduction

Our goal in this article is to review common types where we can store values and what benefits we can get with each way. In the begging, we should understand the reason why we need to make all these efforts to store credentials or other secrets especially. It`s too dangerous to add secrets directly to config files and push these changes to the control version system (CVS) such as git.

It is pretty simple to answer this question. All developers who will work on a project get access to the secret values. You can be sure in your team that they never reveal internal company`s data to others, but their working machines could be hacked in different ways. The best practice would be to separate code and secret configuration values.

But we need access to these values for our application. .NET provides a few values on how we can separate secrets from code.

Generate configuration file during deployment and add it to deploy artifacts. ( it`s not a .net feature, as you can understand )
Environment variables
Azure Key Vault

Generate configuration file during deployment

This flow requires additional efforts to maintain secrets. The responsible person who will do it will have access to all secrets, and it is still a vulnerability of all projects. Such files could be generated per environment, and a dev version could be added to CVS to help developers run the project on a local machine without additional efforts.

Environment variables

We need to define instruction for developers on variables they need to set up in the local environment. Also, the DevOps team is responsible for proper maintenance of these secrets and proper rotation of them.

Azure Key Vault

This way stores secrets in Azure, and as a single source of truth, it provides good practices to rotate secret values and store them encrypted.

Hands-On

In order to follow examples, you need to add the next packages to your solution:

Microsoft.Extensions.Configuration — a base package that contains classes to work with configuration.
Microsoft.Extensions.Configuration.Binder — gives a convenient way to get typed values from configuration.
Microsoft.Extensions.Configuration.Json — allows loading JSON configuration files.
Microsoft.Extensions.Configuration.AzureKeyVault — adds azure key vault provides to configuration.
Azure.Extensions.AspNetCore.Configuration.Secrets — this package allows reading secrets from the azure key vault.
Azure.Identity — contains authentication classes that are used to access the key vault.

Let`s run the following commands in the console to add packages to the project:

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.AzureKeyVault
dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
dotnet add package Azure.Identity

The configuration file has a simple structure with the default configuration:

{
  "NAMESPACE": {
    "SECTIONNAME": {
      "Key": "Value1"
    }
  }
}

Don`t forget to update file properties and copy the file into the output directory:

`cs
using Azure.Extensions.AspNetCore.Configuration.Secrets;
using Azure.Identity;
using Microsoft.Extensions.Configuration;

var keyVaultUrl = "https://dev-readexample.vault.azure.net/";
var settingsPrefix = "NAMESPACE";
var sectionName = "SECTIONNAME";

var builder = new ConfigurationBuilder();

builder.SetBasePath(Directory.GetCurrentDirectory());

builder.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);
builder.AddAzureKeyVault(new Uri(keyVaultUrl), new DefaultAzureCredential(), new AzureKeyVaultConfigurationOptions
{
ReloadInterval = TimeSpan.FromSeconds(3)
});

IConfigurationRoot configuration = builder.Build();
var section = configuration.GetSection($"{settingsPrefix}:{sectionName}");
var value = section.GetValue("key");

Console.WriteLine("Key has value {0}", value);

// delay allows us to update value in azure key vault
await Task.Delay(TimeSpan.FromSeconds(30));

var newValue = configuration.GetValue($"{settingsPrefix}:{sectionName}:key");

Console.WriteLine("Key has value {0}", newValue);
`

Let`s review an example to understand what happens.

We create ConfigurationBuilder and add 2 provides one that allows us to read values from JSON files. And we can grab a configuration that is stored directly in JSON without any request to Azure. Also, we added AzureKeyVaultProvider, and now our configuration can read secrets from Azure. To properly configure AzureKeyVaultProvider, we need to pass the key vault URL and credentials, which should be used to access the key vault.

You can check how DefaultAzureCredential works in the next image:

As you can notice, an additional configuration was provided to AzureKeyVaultProvider that tells to reload settings from KeyVault every 3 seconds. Please be careful with this configuration. Azure changes 0.03$ per 10k requests at the moment of writing the article. The application will check for new value in Azure for key 12 times per minute. With simple math calculations:
12 * 60 min * 24hours * 30 days = 518400 requests / 10000 * 0.03 = 1.5552$ per month.

It`s just for a single secret and single application instance per month.
Also, you should remember that in order to map the JSON setting page in Azure, you should follow the dash notation as in the following image:

Conclusion

If you are going to host your application in Azure, it`s better to follow best practices and store your secrets in Azure Key Vault. Just be aware of how often your application loads data from the key vault because it can increase your monthly bill. Good luck.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

Why Is SOLID Gold Standard In .NET?

Andrew — Tue, 22 Feb 2022 08:30:28 +0000

These five letters become like a threshold that divides young developers from mature ones. I have visited a lot of tech interviews from both sides, and as a reviewer, I can say that question about SOLID could be a killing bullet for developers.

I want to show that it is pretty easy to understand solid. Let`s recall what does it state for, relying on the wiki.

SOLID is an acronym for five design principles intended to make software designs more understandable, flexible, and maintainable in software engineering.

The Single-responsibility principle
The Open–closed principle
The Liskov substitution principle
The Interface segregation principle
The Dependency inversion principle

We are going to check each of the five principles one by one with examples in c#.

Single Responsibility Principle (SRP)

This one is used by many developers unintendedly because simple logic suggests how to improve our code. Single responsibility tells us to write small classes which do only a single part of logic.

Let`s take a look at some service implementation:

public class Entity
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public class CreateEntityRequest
{
    public string Name { get; set; }
}

public class EntityResponse
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public class Repository
{
    public void Save(Entity entity)
    {

    }
}

public class Service
{
    private readonly Repository _repository;

    public EntityResponse CreateEntity(CreateEntityRequest request)
    {
        if (string.IsNullOrEmpty(request.Name))
        {
            throw new Exception("Validation Exception Name is empty");
        }

        var entity = new Entity
        {
            Name = request.Name,
        };

        _repository.Save(entity);

        return new EntityResponse
        {
            Id = entity.Id,
            Name = entity.Name,
        };
    }
}

I want to highlight that this service violates SRP. Its responsibilities are validation, mapping, and actual business logic. This example illustrates that the service knows a lot about validation rules and how to map create request to entity and entity to the response.

Another thing that becomes much harder when you decide to abandon the SR principle is testing. Testing the above example will cause a lot of code to cover all possible cases, and eventually, it becomes unsupported and takes a lot of time.

public class CreateEntityValidator
{
    public void Validate(CreateEntityRequest request)
    {
        if (string.IsNullOrEmpty(request.Name))
        {
            throw new Exception("Validation Exception Name is empty");
        }
    }
}

public class Mapper
{
    public Entity Map(CreateEntityRequest request)
    {
        return new Entity
        {
            Name = request.Name,
        };
    }

    public EntityResponse Map(Entity entity)
    {
        return new EntityResponse
        {
            Id = entity.Id,
            Name = entity.Name,
        };
    }
}

public class Service
{
    private readonly Repository _repository;
    private readonly CreateEntityValidator _createEntityValidator;
    private readonly Mapper _mapper;

    public EntityResponse CreateEntity(CreateEntityRequest request)
    {
        _createEntityValidator.Validate(request);


        var entity = _mapper.Map(request);

        _repository.Save(entity);

        return _mapper.Map(entity);
    }
}

Now, the code looks better, we moved validation and mapping to separate classes, and the service doesn`t know the internal rules of how these processes work. Now our service does not violate SRP, and in terms of testing, it is pretty easy to test 3 small classes which do a small part of logic.

Open-Close Principle (OCP)

This principle sounds quite tricky and could blow the mind

software entities (classes, modules, functions, etc.) should be open for extension but closed for modification

We`ll look at the situation when we work with a few data sources, and the later amount of external services may be increased.

// provided by external lib
public class S3Client
{
    public IEnumerable<string> GetBucketBlobs()
    {
        return new List<string>
        {
            "s3Blob"
        };
    }
}
// provided by external lib
public class AzureStorageClient 
{
    public IEnumerable<string> GetStorageBlobs()
    {
        return new List<string>
        {
            "AzureBlob"
        };
    }
}


internal class Service
{
    public IEnumerable<string> GetAllBlobs(List<object> clients)
    {
        var blobs = new List<string>();
        foreach(var client in clients)
        {
            if(client is AzureStorageClient)
            {
                blobs.AddRange((client as AzureStorageClient).GetStorageBlobs());
            }
            if (client is S3Client)
            {
                blobs.AddRange((client as S3Client).GetBucketBlobs());
            }
        }

        return blobs;
    }
}

Here is the classic example, you have to work with different clients that provide different contracts but logically, they do the same. The best way would be to use the Adapter pattern.

Take a look at Design Patterns — Adapter .NET

The adapter allows to make the same contract for different implementations, and it perfectly suits this example:

public class S3Client
{
    public IEnumerable<string> GetBucketBlobs()
    {
        return new List<string>
        {
            "s3Blob"
        };
    }
}

public class AzureStorageClient
{
    public IEnumerable<string> GetStorageBlobs()
    {
        return new List<string>
        {
            "AzureBlob"
        };
    }
}

public interface IExternalSource
{
    IEnumerable<string> GetBlobs();
}
public class S3Source : IExternalSource
{
    private readonly S3Client _s3Client;

    public S3Source(S3Client s3Client)
    {
        this._s3Client = s3Client;
    }

    public IEnumerable<string> GetBlobs()
    {
        return _s3Client.GetBucketBlobs();
    }
}

public class AzureSource : IExternalSource
{
    private readonly AzureStorageClient _azureClient;

    public AzureSource(AzureStorageClient azureClient)
    {
        this._azureClient = azureClient;
    }

    public IEnumerable<string> GetBlobs()
    {
        return _azureClient.GetStorageBlobs();
    }
}

public class FtpSource : IExternalSource
{
    private readonly FtpClient _ftpClient;

    public FtpSource(FtpClient ftpClient)
    {
        this._ftpClient = ftpClient;
    }

    public IEnumerable<string> GetBlobs()
    {
        return _ftpClient.GetBlobs();
    }
}

internal class Service
{
    public IEnumerable<string> GetAllBlobs(List<IExternalSource> clients)
    {
        var blobs = new List<string>();
        foreach (var client in clients)
        {
            blobs.AddRange(client.GetBlobs());
        }
        return blobs;
    }
}

As you can see IExternalSource interface was introduced, and proper wrappers were created for different sources. Service implementation was changed to accept a list of IExternalSource.

Let’s understand what does it means to open for extension.

In the example above, we can extend our service capabilities to work with additional sources, as, for example, an FTP source was added. This is the idea of an extension that we can add new functionality to our business logic without touching existing parts. In the real world, our service would be covered with unit tests, and new functionality doesn`t make us rewrite that tests. We just introduced a new source and new unit tests for that separate class.

At the end of this part, we must summarize what close for modification means. The example above demonstrates that to support a new source, we don`t need to touch Service implementation at all. In other words, the service is closed to any code modification.

Liskov-Substitution Principle (LSP)

This principle is closely related to the previous one:

Object and a sub-object (such as a class that extends the first class) must be interchangeable without breaking the program

The Definition states that we should write programs in such a way that it`s possible to use any descendant instead of a base class or interface. It is also very closely related to the interface segregation principle, as we can see a bit later:

cs internal class Service { public IEnumerable<string> GetAllBlobs(List<IExternalSource> clients) { var blobs = new List<string>(); foreach (var client in clients) { blobs.AddRange(client.GetBlobs()); } return blobs; } }

Let`s take a look at the example from OCP. It works and adheres to LSP. Inside method GetAllBlobs, we do not care what kind of instance we actually get. We know a contract of interface and assume that all descendants who implement interface properly implement the GetBlobs method.

This principle forces us not to change child behavior drastically.

Interface Segregation Principle (ISP)

This one is also quite related to principles that we have already learned.

no code should be forced to depend on methods it does not use

In simple words, it means that we should never leave a method empty or throw NotImplementedException

public class Item
{

}

public interface IService
{
    void Create(Item item);
    Item GetItem();
}

internal class Service : IService
{
    public void Create(Item item)
    {
        Console.WriteLine("Item Created");
    }

    public Item GetItem()
    {
        return new Item();
    }
}

internal class ServiceHistoryDecorator : IService
{
    private readonly IService _service;

    public ServiceHistoryDecorator(IService service)
    {
        _service = service;
    }

    public void Create(Item item)
    {
        this._service.Create(item);
        Console.WriteLine("Log info that item was created");
    }

    public Item GetItem()
    {
        throw new NotImplementedException("Logger is only for modification operations");
    }
}

In the example above, you see that ServiceHistoryDecorator throws NotImplementedException because it allows to log only modification operations, but due to inheritance from common interface IService, it`s required to implement a contract with all methods.

`cs
public class Item
{
}

public interface IModificationService
{
void Create(Item item);
}
public interface IService : IModificationService
{
Item GetItem();
}

internal class Service : IService
{
public void Create(Item item)
{
Console.WriteLine("Item Created");
}

public Item GetItem()
{
    return new Item();
}

}

internal class ServiceHistoryDecorator : IModificationService
{
private readonly IService _service;

public ServiceHistoryDecorator(IService service)
{
    _service = service;
}

public void Create(Item item)
{
    this._service.Create(item);
    Console.WriteLine("Log info that item was created");
}

}
`

After small changes code looks better. We extracted modification operation into a separate interface and updated inheritance rules. Now we don`t need to implement read operations in ServiceHistoryDecorator.

Dependency Inversion Principle (DIP)

Don`t miss it with Dependency injection, which is also pronounced a bit similar:

High-level modules should not import anything from low-level modules. Both should depend on abstractions (e.g., interfaces).
Abstractions should not depend on details. Details (concrete implementations) should depend on abstractions.

This principle only sounds unclear; indeed, it`s quite simple, and most .NET developers follow it implicitly.

Terrible example when High-Level component Service directly depends on Low-Level component Repository:

public class Entity
{

}

public class Repository
{
    public void Save(Entity entity)
    {
        //... writes it to database
    }
}

internal class Service
{
    public void Save(Entity entity)
    {
        var repo = new Repository();
        repo.Save(entity);
    }
}

To follow the dependency inversion principle, we need to introduce an abstraction for our repository IRepository and make the service depend on abstraction instead of the concrete repository:

public class Entity
{

}

public interface IRepository
{
    void Save(Entity entity);
}
public class Repository : IRepository
{
    public void Save(Entity entity)
    {
        //... writes it to database
    }
}

internal class Service
{
    private readonly IRepository _repository;

    public Service(IRepository repository)
    {
        _repository = repository;
    }

    public void Save(Entity entity)
    {
        _repository.Save(entity);
    }
}

Conclusion

For .NET developers, it`s pretty easy to follow SOLID principles. Language helps us write code with best practices. As you notice, some principles are highly coupled, and if you violate one of the solid principles, there is a huge chance that another principle is also violated.

Good luck with writing a good code.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

Basic Knowledge of EntityFramework for .Net Developer

Andrew — Mon, 21 Feb 2022 12:47:56 +0000

I want to share essential knowledge about EntityFramework (EF), which should be enough to implement most of the trivial tasks working with the relational database. This article should help young developers to understand EF better and avoid some mistakes, which I did on my way.

Preparation

Firstly let’s prepare a database. It reflects the most trivial case with the post and Author. I decided not to invent the wheel because this article reveals the primary usage of EF and not about some concrete model.

Let`s take a look at database schema:

`cs
-- script to create database and required tables

create table authors(
id uuid primary key,
name text
);

create table posts (
id serial primary key,
title text,
content text,
is_deleted bool,
author_id uuid
);

alter table posts
add constraint posts_authors_fk foreign key (author_id) references authors(id);
`

In the project, we need to include proper NuGet packages:

cs dotnet add package Microsoft.EntityFrameworkCore -v 6.0.0

Besides the EF package, we should include specific NuGet for proper database dialect. We used the Npgsql package and Postgres as a database for examples in this article:

cs dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL -v 6.0.0

EF initial configuration

We are ready to use EF in our project, and it’s time to configure POCO classes that will represent database objects in the .NET world:

`cs
public class Author
{
public Guid Id { get; set; }
public string Name { get; set; }
public virtual ICollection Posts { get; set; }
}

public class Post
{
public int Id { get; set; }
public string Title { get; set; }
public string Content { get; set; }

public bool? IsDeleted { get; set; }

public Guid AuthorId { get; set; }
public virtual Author Author { get; set; }

}
`

As you can see, classes represent almost the same structure as a table in the database. A difference comes with virtual properties. In the case of Author, it’s a list of Posts, and accordingly, the Post entity has virtual Author property. Such properties, also called Navigation properties, allow us to work with flat tables in the objects world.

We need to provide proper configuration for EF to make it understand navigation properties. Also, the Post table has a serial type in the database, and we need to tell EF about this. Furthermore, we should properly map all properties to columns.

I want to share the knowledge that EF gives us a way to provide a mapping between objects and tables in a few different ways. I want to leave entity objects simple as they are right now and not overwhelm them with many attributes. Fluent API provided by EF gives such ability. When you try to make it more straightforward and more visible for the future developer, it’s better to separate DB mappings in different scoped files. Another good point is to make classes for mapping internal and prevent access to them from other projects in the solution.

`cs
internal class AuthorMap
{
public static void Map(ModelBuilder modelBuilder)
{
var table = modelBuilder.Entity().ToTable("authors");

    table.HasKey(t => t.Id);
    table.Property(p => p.Id).HasColumnName("id");
    table.Property(p => p.Name).HasColumnName("name");

    table.HasMany(t => t.Posts).WithOne(t => t.Author);
}

}
`

We defined what property is the primary key for the table and mapped properties accordingly in such mapping. In the end, we described a navigation property and helped EF to understand how entities related to each other.

note: we’ll use this mapping file a bit later

`cs
internal class PostMap
{
public static void Map(ModelBuilder modelBuilder)
{
var sequenceName = "posts_id_seq";
modelBuilder.HasSequence(sequenceName).IncrementsBy(1);
var table = modelBuilder.Entity().ToTable("posts");
table.HasQueryFilter(t => t.IsDeleted != true);

    table.HasKey(k => k.Id);
    table.Property(t => t.Id).HasColumnName("id").UseHiLo(sequenceName);
    table.Property(t => t.Title).HasColumnName("title");
    table.Property(t => t.Content).HasColumnName("content");
    table.Property(t => t.IsDeleted).HasColumnName("is_deleted");
    table.Property(t => t.AuthorId).HasColumnName("author_id");

    table.HasOne(t => t.Author).WithMany(t => t.Posts).HasForeignKey(t => t.AuthorId);
}

}
`

Our mapping for Posts looks similar to authors, and you can notice a sequence name and some code related to it. It comes from PostgreSQL, and if you use another database server, you need to provide another configuration for the autoincremented column.

And finally, we can create our database context:

`cs
public class ExampleDbContext : DbContext
{
private readonly string _connectionString;
public ExampleDbContext(string connectionString)
{
_connectionString = connectionString;
}

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.UseNpgsql(_connectionString);

    base.OnConfiguring(optionsBuilder);
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    PostMap.Map(modelBuilder);
    AuthorMap.Map(modelBuilder);
    base.OnModelCreating(modelBuilder);
}

}
`

Small Checklist

What you should avoid during EF configuration:

selecting name for your .net entities adhere DB table name and don’t use synonyms for this
previous rule is also applicable for navigation properties
try to separate DB mapping from each other it helps read/review code later

Let`s finally use it

We need to verify that it works and the best way to do it is to start using it.

Note: We should asynchronously implement all IO-bound operations; EF provides asynchronous analog to the most supported API.

Add entities to the database

public static async Task AddEntityToDatabaseAsync()
{
    var connectionString = "Server=localhost;Port=5432;Database=test_ef;User Id=postgres;Password=[YOUR_PASSWORD];";
    using var context = new ExampleDbContext(connectionString);

    var author = new Author
    {
        Id = Guid.NewGuid(),
        Posts = new List<Post>(),
        Name = "example author"
    };
    // at this point entity added to EF and it still does not exist in database
    await context.AddAsync(author);

    // we need to save changes and after this invocation entity will be added to database 
    await context.SaveChangesAsync();

    // identical way to insert entity to database

    var newAuthor = new Author
    {
        Id = Guid.NewGuid(),
        Posts = new List<Post>(),
        Name = "example author with attach"
    };
    var authorsSet = context.Set<Author>();
    var attachedEntity = authorsSet.Attach(newAuthor);
    attachedEntity.State = EntityState.Added;

    await context.SaveChangesAsync();
}

Under the hood of AddAsync, EF does something similar to the last approach, and it prepares a set for the proper entity type and attaches the entity with status Added. ChangeTracker tracks these changes, and when you call SaveChangesAsync, it sends all data to the database.

Note: if you are working with web servers, try to save changes at the end of the HTTP request. It helps to protect data integrity and prevent an excess round trip to the database.

Get entities from the database

public static async Task GetEntitiesFromDatabaseAsync()
{
    var connectionString = "Server=localhost;Port=5432;Database=test_ef;User Id=postgres;Password=[YOUR_PASSWORD];";
    using var context = new ExampleDbContext(connectionString);

    var author = new Author
    {
        Id = Guid.NewGuid(),
        Posts = new List<Post>(),
        Name = "example author"
    };
    await context.AddAsync(author);
    await context.SaveChangesAsync();

    var createdAuthorId = author.Id;
    // returns object which should be cast to proper type
    var createdAuthor = await context.FindAsync(typeof(Author), createdAuthorId); 

    var entities = context.Set<Author>();
    // returns strongly typed object because we query typed entities set  
    var typedCreatedAuthor = await entities.FindAsync(createdAuthorId);
    // allows to filter set by any criteria
    var filterSEtByCriteria = await entities.AsNoTracking().FirstOrDefaultAsync(a => a.Id == createdAuthorId);

    // change tracking because per request instance
    context.ChangeTracker.QueryTrackingBehavior = QueryTrackingBehavior.NoTracking;
}

As you can see, when you know the key, you can extract the entity from the database in a few ways. In most cases, FirstOrDefaultAsync helps but be aware of tracking settings. If you don’t mark a request to database AsNoTracking or set it up on context level, EF puts your entity to ChangeTracker. It requires additional resources from the system for reading flow; it’s unnecessary.

Note: Always use AsNotracking for reading operations if you are not going to modify extracted entities later

Load data with navigation properties

By default, when you load entity EF doesn’t load navigation properties to memory. When you access the navigation property, the possibility to get NullReferenceException is high. It is pretty convenient to load entity together with navigation properties just once and use it for in-memory business logic operations.

Note: Be aware of lazy loading. It can cause performance problems that are hard to identify.

public static async Task LoadNavigationPropertyAsync(ExampleDbContext context, int postId)
{
    // without include 
    var postsSets = context.Set<Post>();

    var postWithoutAuthor = await postsSets.FirstOrDefaultAsync(p => p.Id == postId);
    if (postWithoutAuthor.Author == null)
    {
        Console.WriteLine("Loading without include causes null for navigation property");
    }

    var postWithAuthor = await postsSets.Include(p => p.Author)
        .FirstOrDefaultAsync(p => p.Id == postId);

    if (postWithAuthor.Author != null)
    {
        Console.WriteLine("Loading with include gets navigation data from database");
    }
}

As you see, we can use Include to specify which navigation properties we want to load from the database.

Use navigation properties to insert data

EF is quite clever in understanding the relationship between objects and providing proper values for foreign keys.

public static async Task ExampleOfNavigationInsertAsync(ExampleDbContext context)
{
    // add nested entity via navigation property 
    using var transaction = await context.Database.BeginTransactionAsync();
    var author = new Author
    {
        Id = Guid.NewGuid(),
        Posts = new List<Post>(),
        Name = "example author"
    };
    author.Posts.Add(new Post
    {
        Content = "content1",
        Title = "title",
        // AuthorId = author.Id no need to provide it here
    });
    var authors = context.Set<Author>();
    await authors.AddAsync(author);
    await context.SaveChangesAsync();
    await transaction.CommitAsync();
}

As you can see, we can omit AuthorId and EF provides it for us.

Another proper technique that you can notice here is wrapping modified flow into transaction scope. In case of a problem, we can roll back the transaction, and data in the database stays not corrupted.

Note: Working with web servers, try to wrap calls that should modify data into transactions and prevent any corrupted data from being inserted into the database.

Conclusion

EF as ORM simplifies life and works with databases smoothly. In this article, you can find base examples of configuring and working with EF. Some examples contain note which helps you to improve your day-to-day interactions with EF. I will try to prepare all the best practices on using EF in some next articles.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

How to use Polly in .NET

Andrew — Thu, 17 Feb 2022 08:37:43 +0000

In this article, I want to describe a toolset offered by Polly and some bad and good ways to use it. Hopefully, you get a better understanding of resiliency and fault-tolerant code.

Few words about Polly

Polly is a .NET resilience and transient-fault-handling library that allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback in a fluent and thread-safe manner.

Let the story begin with CircuitBreaker

We start or journey from one quite useful resiliency pattern known as Circuit Breaker:

Handle faults that might take a variable amount of time to recover from when connecting to a remote service or resource. This can improve the stability and resiliency of an application.

This quote doesn’t make it clear what a circuit breaker does. I want to describe how it works using a simple example. We need to integrate with API, which provides information about weather and this weather API is not under our ownership. Working with third-party APIs makes us think about a case when another API goes down. We don’t know the reason why 3rd party API went down and when it becomes available again. For our flow, it’s better to skip requests to not working API instead of waiting for a timeout as an operation result. And Circuit Breaker perfectly fits in this game. It breaks a flow and prevents any request to corrupter API for some time.

Let’s dive into examples

public static async Task BasicAsync()
{
        var circuitBreakerPolicy = Policy
        .Handle<Exception>()
        .CircuitBreakerAsync(2, TimeSpan.FromSeconds(1));

    // 2 errors break it for 1 second 

    for (int i = 0; i < 10; ++i)
    {
        try
        {
            Console.WriteLine($"Execution {i}");
            await circuitBreakerPolicy.ExecuteAsync(async () =>
            {
                Console.WriteLine($"before throw exception {i}");
                throw new Exception($"Error {i}");
            });
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Catch ex {ex.Message}");
        }

        await Task.Delay(500);
    }
}

In this example, the circuit breaker opens after two exceptions and, during 1 second, stays open and then again allows us to get an error. It’s a pretty clear example of how it works. Another system has a second break to become available again.

Here is a more complex configuration for the circuit breaker:

public static async Task AdvancedAsync()
{
    var advancedCircuitBreaker = Policy
        .Handle<Exception>()
        .AdvancedCircuitBreakerAsync(0.5, TimeSpan.FromSeconds(2), 3, TimeSpan.FromSeconds(1));

    for (int i = 0; i < 10; i++)
    {
        try
        {
            Console.WriteLine($"Execution {i}");
            await advancedCircuitBreaker.ExecuteAsync(async () =>
            {
                Console.WriteLine($"before throw exception {i}");
                throw new Exception($"Error {i}");
            });
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Catch ex {ex.Message}");
        }

        await Task.Delay(500);
    }
}

We can configure the circuit breaker in a more sophisticated way instead of just a number of errors. We provide that it should open if 50% of requests throw an error during two seconds with the condition that the minimal amount of requests is 3.

Both examples are valid, and it’s our responsibility to decide which configuration is better suited for us.

Timeout policy and policy wrap

Another helpful policy provided by Polly is Timeout. It determines how long the operation can be running and if it exceeds that threshold, the timeout policy force stops invocation and throws an error.

In the following example, I want to combine the timeout policy that throws errors exceeded by timeout with a circuit breaker policy that prevents execution after 100% or errors during the last 3 seconds.

public static async Task TimeoutConsequenceAsync()
{
    var advancedCircuitBreaker = Policy
        .Handle<Exception>()
        .AdvancedCircuitBreakerAsync(1, TimeSpan.FromSeconds(3), 2, TimeSpan.FromSeconds(1));

    var timeoutPolicy = Policy.TimeoutAsync(TimeSpan.FromMilliseconds(1000), TimeoutStrategy.Pessimistic);
    // note: Optimistic cancel operation via cancellation token 

    var wrapPolicy = Policy.WrapAsync(advancedCircuitBreaker, timeoutPolicy);

    for (int i = 0; i < 10; i++)
    {
        try
        {
            Console.WriteLine($"Execution {i}");
            await wrapPolicy.ExecuteAsync(async () =>
            {
                Console.WriteLine($"before throw exception {i}");
                await Task.Delay(TimeSpan.FromMilliseconds(1000));
                Console.WriteLine($"after throw exception {i}");
            });
            Console.WriteLine($"Execution {i} after actual call");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Catch ex {ex.Message}");
        }

        await Task.Delay(100);
    }
}

We created a timeout policy that allows code to be executed up to 1 second, and in the case of the Pessimistic strategy, the timeout policy throws an exception. If we choose an optimistic strategy, we have to configure our code to rely on CancelationToken provided by the timeout policy.

Also, we combined two policies into one complex Policy using Policy.WrapAsync(polices)

It would help if you remembered that the Policy that triggers closer to your code must be placed at a righter position in wrap invocation. In the example above, the timeout policy wraps code, and the circuit policy wraps timeout policy.

If you run the example above, code will be executed two and failed by timeout policy circuit breaker decided that threshold reached and came to the opened state for 1 second then again timeout policy triggered and again circuit comes to open state.

Let’s take a look at what happens when we open tasks for execution simultaneously:

public static async Task TimeoutRandomParallelAsync(){
  var advancedCircuitBreaker = Policy
      .Handle<Exception>()
      .AdvancedCircuitBreakerAsync(1, TimeSpan.FromSeconds(3), 2, TimeSpan.FromSeconds(1));

  var timeoutPolicy = Policy.TimeoutAsync(TimeSpan.FromMilliseconds(1000), TimeoutStrategy.Pessimistic);
  // note: Optimistic cancel operation via cancellation token 

  var wrapPolicy = Policy.WrapAsync(advancedCircuitBreaker, timeoutPolicy);

  var tasks = new List<Task>();
  for (int i = 0; i < 10; i++)
  {
      try
      {
          tasks.Add(wrapPolicy.ExecuteAsync(async () =>
          {
              Console.WriteLine($"before throw exception {i}");
              await Task.Delay(TimeSpan.FromMilliseconds(3500));
          }));
      }
      catch (Exception ex)
      {
          // never come here
          Console.WriteLine($"Catch ex {ex.Message}");
      }

      // without delay all tasks started invocation and circuit breaker doesn`t know about fails 
      await Task.Delay(100);
  }

  try
  {
      await Task.WhenAll(tasks);
  }
  catch (Exception ex)
  {
      // here ex contains first error thrown by list of tasks
      var errors = tasks.Select(t => t.Exception);

      foreach (var error in errors)
      {
          Console.WriteLine($"HERE WE COME {error.Message}");
      }
  }
}

In this example, we created ten tasks and waited for them to be completed. In such an example, the circuit breaker never comes into the game, and we get ten timeout exceptions. Circuit breaker passes request before it gets information that another request threw an error.

This example can demonstrate what happens in the real world when many requests come to our application and the circuit breaker allow them all to hit into the broken part, but after it detects threshold break, the following requests face opened circuit breaker.

What to do when the circuit is open?

Polly provides a convenient way to handle errors with Fallback Policy. Let’s enrich the previous example with the fallback Policy:

public static async Task FallbackWithTimeoutAsync()
{
    var advancedCircuitBreaker = Policy
        .Handle<Exception>()
        .AdvancedCircuitBreakerAsync(0.5, TimeSpan.FromSeconds(2), 3, TimeSpan.FromSeconds(1));

    var timeoutPolicy = Policy.TimeoutAsync(TimeSpan.FromMilliseconds(1000), TimeoutStrategy.Pessimistic);

    var fallback = Policy
        .Handle<BrokenCircuitException>()
        .Or<TimeoutException>()
        .Or<AggregateException>()
        .Or<TimeoutRejectedException>()
        .FallbackAsync((cancellation) =>
        {
            Console.WriteLine("Fallback action");
            return Task.CompletedTask;
        });

    var wrapPolicy = Policy.WrapAsync(fallback ,advancedCircuitBreaker, timeoutPolicy);

    var tasks = new List<Task>();
    for (int i = 0; i < 10; i++)
    {
        try
        {
            tasks.Add(wrapPolicy.ExecuteAsync(async () =>
            {
                Console.WriteLine($"before wait {i}");
                await Task.Delay(TimeSpan.FromMilliseconds(3500));
                Console.WriteLine($"after wait {i}");
            }));
        }
        catch (AggregateException ex)
        {
            // never come here
            Console.WriteLine($"Catch ex {ex.Message}");
        }

        await Task.Delay(500);
    }

    try
    {
        await Task.WhenAll(tasks);
    }
    catch (AggregateException ex)
    {
        // here ex contains first error thrown by list of tasks
        var errors = tasks.Where(t=> t.Exception != null).Select(t => t.Exception);

        foreach (var error in errors)
        {
            Console.WriteLine($"ERROR is {error.Message} {error.GetType()}");
        }

    }
}

We created a fallback Policy that can handle a list of exception types and provide a fallback strategy in that case. Fallback should be specified as most left Policy during Policy.Wrap operation.

What about Retries?

As a developer, we should be careful with retry policies. It can cause a cost spike with a pity configuration and even kill your cluster. Polly has a good list of examples of how to configure retries. I want to highlight that if you need to create a retry policy, it’s better to configure it with exponential delays and a limited count of times.

Conclusion

The circuit breaker is a must-have pattern to use if you deal with distributed systems. As a developer, you should take care of cases when some part of the system doesn’t, and here fallback policy perfectly fits. Also, try to limit external calls with a timeout, and no one likes to wait.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

Single Transaction per Request ASP.NET Core With EntityFramework

Andrew — Wed, 16 Feb 2022 09:29:46 +0000

In this article, we’ll configure ASP.NET to open a single transaction per request and commit it when the request finishes.

Most APIs work with DB under the hood, and It’s bad practice to commit changes separately a few times during HTTP requests. It can cause a lot of round trips to the database just for one HTTP request. Also, it leads to corrupted data if something goes wrong. The Best approach would be to open a single transaction and only when everything goes well commit the transaction. In such a case, we appreciate data integrity, and if something goes wrong with that transaction, we can revert all changes.

Let’s review an example which related to the real world. Assuming that we have an application with a data layer where we enclose all work with data. I’ll use EntityFramework (EF) as ORM for the database in my example. It doesn’t matter what kind of database to use. We’ll skip everything and concentrate on general logic for a single transaction for simplicity.

Let’s define an example DB context:

public class ExampleContext : DbContext
{
}

It was intentionally left empty because, in our example, we don’t care about what happens inside context.

We need to define an attribute that allows handling all DB change requests in a single transaction. It’s our responsibility to use the next attribute and mark proper actions with a single transaction. We can’t add a global filter because some actions use DB context in read-only mode, and we don’t need to define any transaction.

public class SingleTransactionAttribute : ActionFilterAttribute
{
    private readonly ExampleContext _context;

    public SingleTransactionAttribute(ExampleContext context)
    {
        this._context = context;
    }

    public override async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
    {
        var transaction = await this._context.Database.BeginTransactionAsync();
        ActionExecutedContext executedContext = await next();
        var hasError = executedContext.Exception == null || executedContext.ExceptionHandled;
        if (hasError && executedContext.ModelState.IsValid)
        {
            await _context.SaveChangesAsync();
            await transaction.CommitAsync();
        }
    }
}

In a SingleTransactionAttribute, we override the OnActionExecutionAsync method. It allows us to add behavior before and right after the action is executed. We need to begin a new transaction before action execution, and when the action completes without errors, we need to commit the transaction.

Also, as you see, put SaveChangesAsync in this attribute. In order to skip calling it all around the code, we have a single place where we save all changes and commit the transaction. Our business logic code knows nothing when to invoke SaveChangesAsync.

Such assumption strongly relies on the Object tracking mechanism under the hood of EntityFramework, but it’s a topic for another story.

Take a look at basic EntityFramework knowledge

Besides this attribute, we also need to configure Dependency Injection to make a scope per user request and provide a single DbContext instance during the scope:

...
public void ConfigureServices(IServiceCollection services)
{
    ...
    services.AddScoped<ExampleContext>();
    services.AddScoped<SingleTransactionAttribute>();
}
...

Here is an example of how to do it during application startup. We add both DbContext and SingleTransactionAttribute to the service as scoped items. And rely on default ASP.NET behavior to use the client request as a scope.

I hope this article was useful for someone.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

XUnit vs NUnit What to Choose to Write Clean Code Part 1.

Andrew — Tue, 15 Feb 2022 08:33:45 +0000

The question of which test framework to choose can appear for a new project or when the team decided to make an experiment trying to improve some internal problem. It’s well known for .net developers that there are three main frameworks: MSTest, NUnit, and XUnit. MSTest is out of scope for this article. I didn’t meet any project which uses it as a primary test framework. I certainly sure such projects exist, and it could be that developers from these projects have written a comprehensive guide щт why to choose MSTest.

We’ll focus on two frameworks, NUnit and XUnit, and they are both quite good and provide common functionally to write tests. Firstly, we’ll look at each separately and then compare both functionalities.

NUnit

NUnit is a unit-testing framework for all .Net languages. Initially ported from JUnit

As it states on the landing page of NUnit.

We’ll cover the latest version of NUnit. At the moment when the article was written, it was 3.13.2. Execute the following commands to add NUnit for your test project:

dotnet add package NUnit --version 3.13.2
dotnet add package NUnit3TestAdapter --version 4.0.0

With these packages, you get an amazing variety of tools provided by NUnit as attributes. Let’s take a look at some of them, which definitely you need to know:

name	description
TestFixture	marks that class contains tests and allows to pass arguments into constructor
OneTimeSetUp	allows to execute code once before all tests started
OneTimeTearDown	it`s a pair to OneTimeTearDown gives us ability to clean resource when all tests finished
SetUp	executes before each test
TearDown	it`s a pair method to SetUp place where we can clean resources after test execution
Test	allows to mark method as test which should be executed
TestCase	gives ability to pass params to test and make it configurable
Ignore	I hope you will not use it a lot. It skips test case during tests execution
Category	define a category for test quite usefull when you need to run only specify category and not run all tests
Author	this one as you can guess defines who wrote a test
MaxTime	provides a way to setup max execution time for test
Description	allows to add readable description to test

It contains much more tools for developers and allows to configure tests for many scenarios.

Let’s check how it looks in code with all these attributes:

[Author("Andrew", "andrewkulta@akyltech.com")]
[TestFixture]
public class TestExample
{
    [OneTimeSetUp]
    public void OneTimeSetup()
    {
        Console.WriteLine("Setup just once");
    }

    [OneTimeTearDown]
    public void OneTimeTearDown()
    {
        Console.WriteLine("Teardown just once");
    }

    [SetUp]
    public void Setup()
    {
        Console.WriteLine("Setup before each test case");
    }

    [TearDown]
    public void TearDown()
    {
        Console.WriteLine("TearDOwn after each test");
    }

    [Test]
    [Description("")]
    [Author("AnotherAuthor")]
    public void Should_DoNothing()
    {
        Console.WriteLine("Sync test");
    }

    [Test]
    [Category("Async")]
    [MaxTime(100)]
    public async Task Should_DoNothingAsync()
    {
        Console.WriteLine("ASync test");
        await Task.Delay(200);
    }

    [TestCase(1)]
    [TestCase(2)]
    public void Should_BeCase(int param)
    {
        Console.WriteLine($"param is {param}");
    }

    [Ignore("example")]
    public void Should_BeIgnored()
    {
        Console.WriteLine("Never invoked");
    }
}

XUnit is also known as xUnit.net

xUnit.net is a free, open-source, community-focused unit testing tool for the .NET Framework

It was created with an idea to replace nUnit 2.* and 3.*. xUnit provides a set of tools to write clean and more independent tests.

List most used attributes from xUnit:

name	description
Fact	marks method as test and allows to configure custom name for method as well as timeout and skip reason.
Theory	marks method as special type of test theory it means that this test is valid only with certain list of params
InlineDate	allows to provide params for theory tests
Trait	gives ability to setup custom metadata for test such as category or author etc...

Let`s take a look at some examples for listed attributes:

`cs
public class xUnitExample : IDisposable
{
public xUnitExample()
{
Console.WriteLine("Executes before each test as setup");
}

[Fact(DisplayName = "Test description")]
[Trait("Category", "CustomCategory")]
public void Should_BeATest()
{
    Console.WriteLine("I`m a test");
}

[Fact(Timeout = 100)]
public async Task Should_BeAsyncTest()
{
    Console.WriteLine("I`m async test");
}

[Theory]
[InlineData(1)]
public void Should_BeTheory(int param)
{
    Console.WriteLine($"param is {param}");
}

[Fact(Skip = "Ignore")]
public void Should_BeSkipped()
{
    Console.WriteLine("Should never be invoked");
}

public void Dispose()
{
    Console.WriteLine("Executes after each test as teardown");
}

}
`

As you can see, xUnit uses constructor and IDisposable pattern to implement setup and teardown. I faced developers who thought that xUnit requires implementing Destructor if you want to clear resources.

I think NUnit allows us to write more descriptive unit tests with various attributes for different purposes. But if you choose xUnit for your project, you get a cleaner code without all this mess with attributes. The final decision depends on your preferences, or maybe the team gets used to one of these frameworks.

Conclusion

To be honest, it doesn’t matter which framework you will choose. They both provide a set of tools to write tests, and it’s more important to concentrate on tests themselves.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

Add Swagger With NSwag for Your ASP.NET Core API

Andrew — Mon, 14 Feb 2022 16:41:04 +0000

Nowadays, a good API should provide documentation, and there are different tools to succeed in it. A swagger is a tool that was created to help us prepare documentation for our API and allows consumers to try and start using it efficiently.

Let’s clarify what the difference between OpenAPI and Swagger is?

OpenAPI is a standard format to define structure and syntax REST APIs

A swagger is a tool that allows the implementation of OpenAPI.

For .net developers, two packages provide the functionality to build the documentation:

NSwag
Swashbuckle

In this article, we will look at the basic configuration for one of them called NSwag. They both have pretty similar structures. And both of them generate documentation relying on API code. As developers, we don`t need to do anything else except writing well-known code for your API endpoints. Providing a proper configuration is enough, and NSwag will pick up all info directly from controllers.

Initial setup

First, what you need to add is the NuGet package:

dotnet add package NSwag.AspNetCore

After installing the package, let`s configure swagger documentation. In the Startup file, we have to add swagger documentation service to the, and we need to call AddSwaggerDocument with proper configuration.

The main parameters which we need to specify are:

Title — title for the swagger document

Version — allows specifying documentation`s version

Commonly, an authorization mechanism protects API, and the swagger tool allows you to specify how authorization will be provided and allows you to set it up.

DocumentProcessors — gives the ability to provide security tokens in request. We need to add SecurityDefinitionAppender in code to achieve it.

The final version will look like this:

cs services.AddSwaggerDocument(document => { document.Title = "Project API"; document.Version = "v1"; document.DocumentProcessors.Add( new SecurityDefinitionAppender("JWT Token", new OpenApiSecurityScheme { Type = OpenApiSecuritySchemeType.ApiKey, Description = "JWT Token", Name = "Authorization", In = OpenApiSecurityApiKeyLocation.Header }) ); document.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT Token")); });

The next step will be to configure ApplicationBuilder to use OpenAPI and UI:

`cs
OpenApiSchema[] schemes = new[] {
OpenApiSchema.Http,
OpenApiSchema.Https
};

app.UseOpenApi(s => {
s.Path = "api/swagger/{documentName}/swagger.json";
s.PostProcess = (document, request) => { document.Schemes = schemes; };
});
app.UseSwaggerUi3(s => {
s.DocumentPath = "api/swagger/{documentName}/swagger.json";
s.Path = $"/api/swagger/ui";
});
`

Conclusion

It`s pretty simple to configure swagger documentation for API and provide convenient UI for consumers who will use it. When you start a new project, try to give a convenient way for consumers to call your API, and swagger will be a good choice.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

Decorator and Single Responsibility Perfectly Play Together.

Andrew — Mon, 14 Feb 2022 08:40:56 +0000

It is so often to write service with business logic and give it a lot of responsibility. When I started my career, I was guilty of doing such a thing. And testing a complex service that handles many different logical parts is like a nightmare. Step by step, trying to make my life easier, I`ve reopened decorator ( design pattern ) for myself.

What is a Decorator?

A decorator is a structural design pattern that lets you attach new behaviors to objects by placing these objects inside special wrapper objects that contain the behaviors.

It is pretty clear from the definition that decorator should be our silver bullet when we need to add some behavior for the existing codebase or when we want to design a good system. That doesn`t mean using a decorator for any small piece of logic that we want to add. As developers, we should consciously design our system and avoid writing tons of structure code just for a small piece of logic.

Is Single Responsibility related?

Let me recall what the definition of Single Responsibility is?

The single-responsibility principle (SRP) is a computer-programming principle that states that every module, class, or function in a computer program should have responsibility for a single part of that program’s functionality, and it should encapsulate that part.

Take a moment to read about SOLID principles.

And here, we get a perfect fit. With single responsibility, we design our components so that they are doing just one thing. With a decorator, we add additional behavior to our logical pipeline, and it`s like a chain of small logic pieces executed one by one.

Here are some examples from my experience when the decorator played exceptionally well.

Basic Setup

For example, we can take a situation when we store data in a database. There are always logical operations to prepare data and store it in a database. Also, later, we want to send a notification that the new entity was stored in the database:

`
public class Entity
{
public string Name { get; set; }
}

public interface IService
{
void Save(Entity entity);
}

public class Service : IService
{
public void Save(Entity entity)
{
Console.WriteLine("Save entity");
}
}
`

The current code is a good example where the decorator fits the best. There are two logical operations to store entities in the database and send notifications. We should create ServiceDecorator, responsible for sending notifications, and there is no need to add additional logic for our existing service. It stays as it is without any modification. We are getting a simple new service that can be covered with a separate set of unit tests.

`
public class ServiceDecorator : IService
{
private readonly IService _service;

public ServiceDecorator(IService service)
{
    _service = service;
}

public void Save(Entity entity)
{
    _service.Save(entity);
    Console.WriteLine("Send notification about saved entity");
}

}
`

Conclusion

Separating logic pieces using a design pattern decorator helps us to make code more maintainable and testable. Consider using a decorator as your reliable tool when you face a situation to add new logic.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

Functional Testing for ASP.NET Core API

Andrew — Sun, 13 Feb 2022 09:54:17 +0000

Functional testing is the next level above the unit testing and gives us confidence that the code we wrote works as intended. If we are talking about functional testing in the scope of ASP.NET, we mean how we test our API.

What actually functional testing is?

Functional testing is the process through which we determine if a piece of software is acting following pre-determined requirements. It uses black-box testing techniques, in which the tester does not know the internal system logic.

In the scope of API, we need to prepare possible requests that we expect to get and be sure that endpoints return a proper response for any payload.

Should we even spend time on it?

Definitely! If you don`t write integrational tests, then functional testing is a solution to ensure that your code has fewer bugs than it could have. When you can write integrational tests as well, it should be simple to reuse a shared codebase for functional and integrational tests. One difference will be in the proper environmental setup.

Let`s define a simple API

Our controller contains only single action to create some entity for test purposes. Our business rules may require any entity, which does not matter for our test example. Besides, we should remember about authentication nowadays. Security compliance requires protecting API with any authentication. Let`s assume that the current API requires an Authorization header with a Bearer token.

`cs
[ApiController]
public class MyController : ControllerBase
{
private readonly IService _service;

public MyController(IService service)
{
    _service = service;
}

[HttpPost("entities")]
[ProducesResponseType(typeof(CreateResponse), (int)HttpStatusCode.OK)]
[ProducesResponseType(typeof(ExceptionResponse), (int)HttpStatusCode.BadRequest)]
public Task<CreateResponse> CreateAsync([FromBody] CreateRequest request)
{
    return _service.CreateAsync(request);
}

}
`

What will the functional test look like for this controller?

In our test project, I used NUnit as a test framework, but it is up to you to choose which better suits your needs. NUnit has all the required functionality to write good tests. Also, it`s pretty popular on the market.

Let`s add the following packages to the test project:

cs dotnet add package NUnit dotnet add package NUnit3TestAdapter

Take a time to read about test frameworks in .NET:

`cs
[TestFixture]
public class ApiControllerTests
{
private const string CreateUrl = "/entities";

private readonly TokenBuilder _tokenBuilder = new();

private TestServer? _server;
private HttpClient? _client;

[SetUp]
public void Setup()
{

    var settings = new Settings
    {
        SymmetricFuncTestKey = "your key for functional tests"
    };

    var builder = new WebHostBuilder()
        .UseStartup<Startup>()
        .ConfigureTestServices(services =>
        {
            // Mock your external services here
        })
        .ConfigureServices(services =>
        {
            // Change authentication to use bearer token which signed by symmetric key
            services.PostConfigure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options =>
            {
                options.TokenValidationParameters = new TokenValidationParameters
                {
                    IssuerSigningKey =
                        new SymmetricSecurityKey(Encoding.UTF8.GetBytes(settings.SymmetricFuncTestKey)),
                    ValidateIssuerSigningKey = true,
                    ValidateIssuer = true,
                    ValidateAudience = true,
                    ValidateLifetime = true,
                    ValidIssuer = TestConstants.Issuer,
                    ValidAudience = TestConstants.Audience,
                };
            });
        });
    _server = new TestServer(builder);
    _client = _server.CreateClient();
}

[Test]
public async Task CreateAsync_Should_ReturnNotAuthenticated_When_RequestWithoutAuthToken()
{
    // Arrange
    var request = new CreateRequest
    {
        PropertyName = "propertyValue"
    };
    var json = JsonConvert.SerializeObject(request);
    using var data = new StringContent(json, Encoding.UTF8, "application/json");

    // Act
    var response = await _client?.PostAsync(CreateUrl, data)!;

    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.Unauthorized);
}

[Test]
public async Task CreateAsync_Should_Return400_When_RequestValidationFailed()
{
    // Arrange
    var request = new CreateRequest();
    var json = JsonConvert.SerializeObject(request);
    using var data = new StringContent(json, Encoding.UTF8, "application/json");
    var token = await _tokenBuilder.BuildJWTToken();
    _client?.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

    // Act
    var response = await _client?.PostAsync(CreateUrl, data)!;

    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
}

[Test]
public async Task CreateAsync_Should_ReturnCreateResponse()
{
    // Arrange
    var request = new CreateRequest
    {
        PropertyName = "propertyValue"
    };
    var json = JsonConvert.SerializeObject(request);
    using var data = new StringContent(json, Encoding.UTF8, "application/json");
    var token = await _tokenBuilder.BuildJWTToken();
    _client?.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

    var expected = new CreateResponse
    {
        PropertyName = "propertyValue"
    };

    // Act
    var response = await _client?.PostAsync(CreateUrl, data)!;

    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.OK);
    var responseBody = await response.Content.ReadAsStringAsync();
    var responseObject = JsonConvert.DeserializeObject<CreateResponse>(responseBody);
    responseObject.Should().BeEquivalentTo(expected);
}

}
`

We should cover that API endpoint protected by authentication, and clients can not request it without a proper token. To do this, we need to prepare a test server with a proper authentication setup. To do it in Startup, we need to override JwtBearerOptions with our test authentication, which relies on auth token signed by SymmetricSecurityKey. To comply with security rules, we should avoid storing any secrets in code, and I don`t suggest you violate this rule even for test projects.

When the authentication configuration is ready, we can generate the proper token to execute business logic in test cases. We can separate token generation into TokenBuilder and use it to get auth token.

Conclusion

I hope you feel that functional tests are pretty simple and allow you to verify your API each time something changes. We often include functional tests as a step in your build pipeline, and it gives you confidence that everything works well before deploying to the production environment.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/

Model Validation Using FluentValidation in ASP.NET

Andrew — Fri, 11 Feb 2022 12:47:42 +0000

One of the requirements for a good API is the ability to validate input relying on different business rules. As developers, we always care about validation when getting any data from clients.

The Source code used in the article you can find in our GitHub repository.

ASP.NET has a built-in mechanism to validate input payloads on the API level. But it’s limited when we are trying to validate input payload with custom business rules. We can move validation inside our business layer and apply our custom validation for input models. Choosing this decision, we are making controllers thin. It just makes a proper model binding and invokes the required service method. Functional tests could cover such behavior, and we don’t need to write unit tests for such thin controller actions.

We can write our custom validation rules, invent a new validation tool and come to a not so handy code with many ifs. in this case, FluentValidation comes into play.

FluentValidation is a library for building strongly-typed validation rules.

Hands-On

Let’s start diving into the code:

public class ApiController : BaseController
{
    private readonly IService _service;

    public TimeEntryController(IService service)
    {
        _service = service;
    }


    [ProducesResponseType(typeof(Response), StatusCodes.Status201Created)]
    [ProducesResponseType(typeof(ExceptionModel), StatusCodes.Status400BadRequest)]
    [HttpPost]
    public async Task<ObjectResult> CreateAsync([FromBody] CreateRequest request)
    {
        var response = await this._service.CreateAsync(request);
        return this.Ok(response);
    }
}

The controller becomes clean and straightforward. ASP.NET still applies validation for model fields, but business validation happens in the service layer.

public class Service
{
    private readonly IValidationService _validationService;

    public TimeEntryService(IValidationService validationService)
    {
        _validationService = validationService;
    }

    public async Task<Response> CreateAsync(CreateRequest request)
    {
        this._validationService.EnsureValid(request);
        // Implementation
        return new Response();
    }

}

The first thing we want to do before starting the implementation for business logic is to apply our validation to the input payload. Each payload requires a proper validator, and it causes a situation when we need to inject many validators into our service to validate input models. It’s better to avoid such cases and introduce another service responsible for model validation only, and it hides all complexity of business validation from other services.

public class ValidationService
{
    private readonly IDictionary<Type, Type> _validators;
    private readonly IServiceProvider _serviceProvider;

    public ValidationService(IServiceProvider serviceProvider)
    {
        this._serviceProvider = serviceProvider;
        this._validators = new Dictionary<Type, Type>
        {
            { typeof(CreateRequest), typeof(CreateRequestValidator) },
        };
    }

    private AbstractValidator<T> GetValidator<T>()
    {
        var modelType = typeof(T);
        var hasValidator = this._validators.ContainsKey(modelType);
        if (hasValidator == false)
        {
            throw new Exception("Missing validator");
        }

        var validatorType = this._validators[modelType];
        var validator = _serviceProvider.GetService(validatorType) as AbstractValidator<T>;
        return validator;
    }

    public void EnsureValid<T>(T model)
    {
        var validator = this.GetValidator<T>();
        var result = validator.Validate(model);
        if (result.IsValid == false)
        {
            throw new Exception(result.ToString());
        }
    }
}

We have a proper structure for validation and are ready to add model validators. FluentValidation gives us a base class AbstractValidator to inherit for our custom validators.

public class CreateRequestValidator : AbstractValidator<CreateRequest>
{
    public CreateRequestValidator()
    {
        RuleFor(r => r.Name).Required();
        RuleFor(r => r.Date.ToUniversalTime()).LessThan(DateTime.UtcNow);
    }
}

Conclusion

We got a clean way to separate validation for input requests into small classes. We can write complex validators that rely on business rules, and it’s simple for us to test validators as a small independent part of the solution.

Any questions or comments? Ping me on LinkedIn or comment below. And if you liked this post, please give it a clap and share it with all of your friends.

Twitter: https://twitter.com/KyliaBoy
Linkedin: https://www.linkedin.com/in/andrew-kulta/

More articles you can find at:
https://blog.akyltech.com/