Monthly Archives: January 2020

Pimp your repo with GitHub Actions!

Do you have a GitHub account with a repository? Improve it with GitHub Actions! GitHub Actions lets you build your own workflows triggered by all kinds of events from your repositories. If you go and check this website, it looks very promising.

Let’s start with a build

To start working with GitHub Actions, just go to Actions tab in your repository page.

As my repo is built in .Net Core, I can choose this template that GitHub suggests me. After that, we will be able to edit yml file to set up our first workflow. Let’s check how it looks like:

name: .NET Core

on: 
    push:
        branches:
            - github-actions

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.100
    - name: Build with dotnet
      run: dotnet build --configuration Release

What to notice:

  • “on” tells us what repository event will trigger our flow. Mine will be triggered by a push to branch “github-actions”
  • “jobs” – each of those will be visible as a separate big steps
  • “build” – job name, that can have multiple small steps
  • “runs-on” identify on which operating system workflow is going to be run. You can choose from: ubuntu-latest, macos-latest and windows-latest and because .Net Core can be built on linux, I choose ubuntu-latest

After a few tries to get it right, it resulted as this:

Let’s run unit tests

My repository has a project dedicated to unit tests, so I’d like to run it and check if all tests are passing. In order to achieve that, I just need to add a few lines to my yml file.

name: .NET Core

on: 
    push:
        branches:
            - github-actions

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.100
    - name: Build with dotnet
      run: dotnet build --configuration Release
    - name: Run unit tests
      run: dotnet test --no-build --configuration Release

After committing that file, my workflow was run instantly and it took only under a minute to see the results.

What about code coverage?

One of the cool things that we use are actions provided by other users. In order to check our project code coverage, we need to do some things on our side, but to expose the result, we can integrate with Coveralls.io. Let’s go step by step.

The first thing we need to do is to install coverlet.msbuild nuget package in our test projects. This will enable us to generate code coverage file in lcov format.

For code coverage, I created a separate flow.

name: Code coverage

on: 
    push:
        branches:
            - github-actions

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      - name: Setup .NET Core
        uses: actions/setup-dotnet@v1
        with:
           dotnet-version: 3.0.100
      - name: Generate coverage report
        run: |
          cd ./Tests/TicketStore.Tests/
          dotnet test /p:CollectCoverage=true /p:CoverletOutput=TestResults/ /p:CoverletOutputFormat=lcov
      - name: Publish coverage report to coveralls.io
        uses: coverallsapp/github-action@v1.0.1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          path-to-lcov: ./Tests/TicketStore.Tests/TestResults/coverage.info   

This is a slightly more complicated case, where we run “dotnet test” with additional parameters to output code coverage. Then we use coverallsapp GitHub Action to integrate with Coveralls.io. In order to make it secure, we use an existing GitHub token. The result can be checked on the Coveralls page.

Let’s add a cherry on top. Coveralls.io generates a badge, that we can use in our Readme.md file. If I add a link like this at the top:

![Build Status](https://github.com/mikuam/TicketStore/workflows/.NET%20Core/badge.svg?branch=github-actions) [![Coverage Status](https://coveralls.io/repos/github/mikuam/TicketStore/badge.svg?branch=github-actions)](https://coveralls.io/github/mikuam/TicketStore?branch=github-actions) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/mikuam/TicketStore/blob/master/LICENSE)

Then I can finally see my badges.

Go check for yourself: https://github.com/mikuam/TicketStore

Why it’s so exciting?

I found GitHub Actions very exciting, because:

  • it’s free! I host many of my pet projects on GitHub and it never cost me a dime, but now I can configure CI/CD process for free as well
  • it supports many languages and frameworks. Even for .Net Framework projects that do not run on .Net Core, I can build them on windows and set up the whole process. I can even run PowerShell scripts
  • I can do more and automate things like deploying to Azure or creating NuGet package

Important thing that I noticed is that it doesn’t work with projects in .Net Core 3.1, but when I updated projects to .Net Core 3.0 it worked fine.

I really enjoyed playing around with GitHub Actions and felt a bit like a DevOps guy:) I’m not very experienced in building infrastructure like that, but it was very simple and intuitive. And those badges… now my repository looks professional! 🙂

ASP.Net Core 3 – configuration

In this chapter, we will cover how we can use configuration in ASP.Net Core 3. But before diving in, let’s see for a moment how it looked in plain old ASP.Net

Configuration before .Net Core

In old ASP.Net configuration was handled typically in only one XML file – Web.config. It was a place where everything was placed. From connection strings to assembly versions and detailed framework settings. This file got bigger and bigger while our project grew and was hard to read. Luckily you could use different files if you link them in the Web.config. Here is how the most important part of this file looked like:

The XML format was perfectly readable, but you would need to follow a specific convention. Let’s now see how things changed in .Net Core.

New possibilities

In .Net Core 3 things are completely different:

  • configuration can be stored in many files and most common format is JSON
  • we can follow our own format
  • we can have nesting
  • configuration can be parsed to whole classes with nested objects
  • we can make configuration refreshable when an application is running, without the need to restart it

Instead of having a configuration in an XML format, in .Net Core we have much more possibilities. Here are the sources that we can use(that are supported by default by the framework):

  • Azure Key Vault
  • Azure App Configuration
  • Command-line arguments
  • Directory files (INI, JSON, XML)
  • Environment variables (by default prefixed by DOTNET_)
  • In-memory .Net objects
  • Settings files
  • and custom providers

Note that variables can be overridden when another source provides the same variable. Then an order that we apply configuration with is important.

One more thing – we can have different configurations for the environment. In order to achieve that, we can suffix our configuration files with environment names. We have environment names set by the framework to: development, staging, production. So we can name our files like this:

  • appsettings.json – that would contain development variables
  • appsettings.production.json – that would contain production variables

Let’s use a configuration in .Net Core 3

First, let’s have an example of an appsettings.json configuration file:

In this configuration file, I have an Email section for configuration to send e-mails. In order to fetch the whole configuration at once, I’ll add three classes:

    public class ServiceConfiguration
    {
        public ConnectionStringsConfiguration ConnectionStrings { get; set; }

        public EmailConfiguration Email { get; set; }
    }

    public class EmailConfiguration
    {
        public string SmtpServerAddress { get; set; }

        public int SmtpServerPort { get; set; }

        public string SenderAddress { get; set; }
    }

    public class ConnectionStringsConfiguration
{
public string DB { get; set; }
}

ServiceConfiguration represents whole configuration and EmailConfiguration represents Email section.

Let’s now go to my Startup class. IConfiguration is an interface for handling configuration, provided by the framework and registered in DI by default. In ConfigureServices we can bind configuration and register it in Dependency Injection container.

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        // configuration
        var serviceConfiguration = new ServiceConfiguration();
        Configuration.Bind(serviceConfiguration);
        services.AddSingleton(serviceConfiguration);
    }

Notice that we need just those 3 lines to make it work. Now let’s see how we can implement class, that would send e-mails.

    public class EmailSenderService : IEmailSenderService
    {
        private readonly EmailConfiguration emailConfiguration;
        private readonly SmtpClient _client;

        public EmailSenderService(ServiceConfiguration configuration)
        {
            emailConfiguration = configuration.Email;
            _client = new SmtpClient(emailConfiguration.SmtpServerAddress, emailConfiguration.SmtpServerPort);
        }

        public async Task SendEmail(string emailAddress, string content)
        {
            var message = new MailMessage(emailConfiguration.SenderAddress, emailAddress)
            {
                Subject = content
            };

            await _client.SendMailAsync(message);
        }
    }

This is programming pleasure in its purest form. Notice what we are injecting ServiceConfiguration, that is our representation of configuration in code. We do not need to use or parse JSON files, digg for nested variables. We just fetch configuration the way we defined it – simple.

What you don’t need to do

In many tutorials and even in official Microsoft documentation you could see, that in order to read appsettings.json file, you would need to make this change in Program.cs file:

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("appsettings.json");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });

The truth is that appsettings.json file will be read by default by the framework without using ConfigureAppConfiguration.

This can cause you problems when deploying to Azure. When I was doing it for the first time it took me hours to figure that out. I set up variables in App Sevice configuration, but they were overridden by local appsettings.json file because of this line. This configuration was applied after reading the configuration from App Service. You can safely remove this line.

 

Hope you enjoyed this post, you can have a look at the code posted here on my Github:

https://github.com/mikuam/TicketStore

 

ASP.Net Core 3 – Dependency Injection

Dependency Injection is a fundamental concept in computer programming. Successfully implemented in many programming languages. What makes it so useful and how .Net Core 3 supports it?

Let’s start with the definition.

Dependency Injection is a software design pattern where dependencies are not created by the client, but rather passed to the client.

In common usage, instead of creating dependencies by new keyword, we will define what we need. We delegate the responsibility of passing those to the injector. Class does not need to know how to create dependency and it’s not a part of its logic.

With a separation of creation and behavior of our service we can build loosely coupled services. In our classes, we concentrate on how it’s going to behave. 

This concept, Dependency Injection, is a part of a broader concept – Inversion of Control. Dependency Injection, DI for short, follows two SOLID principles: dependency inversion and single responsibility principle. This concept is crucial for creating well-designed and well-decoupled software, it’s just a must-have.

Why creating dependencies on your own is a bad idea?

    var ratingsProvider = new MovieRatingProvider(new MoviesClient("connection"), 3);
  • to change implementation of a dependency (in this case MovieRatingProvider), we need to change all places where it is used
  • to create dependency we need to create all of its dependencies as well (MoviesClient)
  • it’s hard to write unit test – dependencies should be easily mocked. In test we do not want to create MoviesClient, we want to mock it and test MovieRatingProvider

Did you know? There is a way of programming, where you are not allowed to use new keyword outside of the dedicated factory. So you not only delegate creating dependencies to the DI, but also create factories to create all other objects. It’s a good concept, that also not always makes sense.

Practical example

Let’s say we have a Web API for getting events. We have EventsController, that gets events from EventsProvider and it gets movie ratings from MovieRatingProvider. On the schema it will look like this:

Now lets see the code, EventsController looks like this:

    [Route("[controller]")]
    [ApiController]
    public class EventsController : ControllerBase
    {
        [HttpGet]
        public IActionResult Get()
        {
            try
            {
                var provider = new EventProvider();

                return new JsonResult(provider.GetActiveEvents());
            }
            catch (Exception)
            {
                // logging
                return StatusCode(StatusCodes.Status500InternalServerError);
            }
        }
    }

You see that EvenProvider, a dependency, is created by new keyword. Here is how it looks like:

    public class EventProvider
    {
        public IEnumerable<Event> GetActiveEvents()
        {
            var events =  GetAllEvents();

            return ApplyRatings(events);
        }

        private IEnumerable<Event> ApplyRatings(IEnumerable<Event> events)
        {
            var ratingsProvider = new MovieRatingProvider();
            var movieRatings = ratingsProvider.GetMovieRatings(
                events.Where(e => e.Type == EventType.Movie)
                      .Select(m => m.Title));

            foreach (var rating in movieRatings)
            {
                var eventToRate = events.FirstOrDefault(e => e.Title == rating.Key);
                if (eventToRate != null)
                {
                    eventToRate.Rating = rating.Value;
                }
            }

            return events;
        }

        private static IEnumerable<Event> GetAllEvents()
        {
            // some list here
            return Enumerable.Empty<Event>();
        }
    }

EventProvider is a bit more complicated. It get all events and then for movies it searches for movie ratings and try to apply them. Last dependency – MovieRatingProvider looks like this:

    public class MovieRatingProvider
    {
        public IDictionary<string, decimal> GetMovieRatings(IEnumerable<string> movieTitles)
        {
            var random = new Random();

            var ratings = movieTitles
                .Distinct()
                .Select(title => new KeyValuePair<string, decimal>(title, (decimal)random.Next(10, 50) / 10));

            return new Dictionary<string, decimal> (ratings);
        }
    }

The first step

What should be the first step to introduce Dependency Injection? Interfaces! We need to introduce interfaces for all our dependencies:

    public interface IEventProvider
    {
        IEnumerable<Event> GetActiveEvents();
    }

    public interface IMovieRatingProvider
    {
        IDictionary<string, decimal> GetMovieRatings(IEnumerable<string> movieTitles);
    }

And we need to decorate our classes with it:

public class EventProvider : IEventProvider

public class MovieRatingProvider : IMovieRatingProvider

The second step

We need to use our interfaces, instead of concrete classes. How do we do that? We need to pass an interface to our class.

There are two popular ways:

  • constructor injection
  • property injection

We will use the first one and I think this is a better one because the constructor is the one place that gathers all dependencies together. Let’s see how it looks in EventsController:

    [Route("[controller]")]
    [ApiController]
    public class EventsController : ControllerBase
    {
        private readonly IEventProvider _eventProvider;

        public EventsController(IEventProvider eventProvider)
        {
            _eventProvider = eventProvider;
        }

        [HttpGet]
        public IActionResult Get()
        {
            try
            {
                return new JsonResult(_eventProvider.GetActiveEvents());
            }
            catch (Exception)
            {
                // logging
                return StatusCode(StatusCodes.Status500InternalServerError);
            }
        }
    }

We are passing IEventProvider in the constructor and save it as private property. It will not be available outside of that class, but you will be able to use the same instance of EventProvider in every method of your class, brilliant!

Now let’s look at the EventProvider:

    public class EventProvider : IEventProvider
    {
        private readonly IMovieRatingProvider _movieRatingProvider;

        public EventProvider(IMovieRatingProvider movieRatingProvider)
        {
            _movieRatingProvider = movieRatingProvider;
        }

        public IEnumerable<Event> GetActiveEvents()
        {
            var events =  GetAllEvents();

            return ApplyRatings(events);
        }

        private IEnumerable<Event> ApplyRatings(IEnumerable<Event> events)
        {
            var movieRatings = _movieRatingProvider.GetMovieRatings(
                events.Where(e => e.Type == EventType.Movie)
                      .Select(m => m.Title));

            foreach (var rating in movieRatings)
            {
                var eventToRate = events.FirstOrDefault(e => e.Title == rating.Key);
                if (eventToRate != null)
                {
                    eventToRate.Rating = rating.Value;
                }
            }

            return events;
        }

        private static IEnumerable<Event> GetAllEvents()
        {
            // some list here
            return Enumerable.Empty<Event>();
        }
    }

An implementation of IMovieRatingProvider is also passed with constructor injection and saved in a private property. All is ready for…

The Final step

In .Net Core 3 support for Dependency Injection is built-in into the framework, therefore, you don’t need to do much to make it work. All you need to do is to go to Startup class and in ConfigureServices method, add registrations of your services.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();

        services.AddScoped<IMovieRatingProvider, MovieRatingProvider>();
        services.AddScoped<IEventProvider, EventProvider>();
    }

I added services.AddScoped methods, that bind an interface to the class that we implement. This is how the framework knows what instance of a class passes when you define your dependency with an interface. Simple as that, those where all of the changes that needed to be introduced to make it work. Let’s see the new application schema side by side with the old one:

Single point of configuration

The Startup class and ConfigureServices method is the only place where we need to put configuration for the whole application. Even if you are using multiple projects, you will need to configure DI only once in Startup class. This applies for a single executable project, like Web API or ASP.Net website. If you have two projects like this in your solution, you would need to configure DI in both of them.

Service lifetimes

You probably noticed that I used AddScoped method to register my dependencies. This is one of the three service lifetimes that you can use:

  • Transient (AddTransient)
  • Scoped (AddScoped)
  • Singleton (AddSingleton)

Those service lifetimes are pretty standard for any Dependency Injection container. Let’s have a quick look at what they are for.

Scoped lifetime – the most popular one. If you register your services as scoped, it will be created only once per request. It means, that whenever you use the same interface representing your dependency, the same instance will be returned within one request. Let’s have a look at this simple example:

Here when ProductController is called, it depends on ProductService and OrderService, which also depends on ProductService. In this case .Net Core 3 DI will resolve ProductService dependency twice, but it will create ProductService once and return the same object in both places. This will happen in scoped lifetime, because it is the same request. In most cases, you should be using this one.

Transient lifetime – if you register your service with a transient lifetime, you will get a new object whenever you fetch it as a dependency, no matter if it is a new request or the same one

Singleton lifetime – this is the most tricky one. Singleton is a design pattern that is very well known. In this pattern whenever you use an object, you will get the same instance of it, every time, even in a different request or a different thread. This is an invitation to problems and this is also why it is called an antipattern sometimes. With singleton lifetime you will get the same instance of your object every time, for the whole lifetime of your application. It’s not a bad idea to use singleton, but you need to implement it in a thread-sefe manner. It may be useful whenever the creation of an object is expensive (time or resource-wise) and you would rather keep it in memory for the next usage, then creating it every time. For example, you can use a singleton to create a service to send an email. Creating SmtpClient is expensive and can be done only once.

    public class EmailSenderService : IEmailSenderService
    {
        private readonly IConfiguration _configuration;

        private readonly SmtpClient _client;

        public EmailSenderService(IConfiguration configuration)
        {
            _configuration = configuration;

            var smtpServerAddress = _configuration.GetValue<string>("Email:smtpServerAddress");
            var smtpServerPort = _configuration.GetValue<int>("Email:smtpServerPort");
            _client = new SmtpClient(smtpServerAddress, smtpServerPort);
        }

        public async Task SendEmail(string emailAddress, string content)
        {
            var fromAddress = _configuration.GetValue<string>("Email:senderAddress");
            var message = new MailMessage(fromAddress, emailAddress);
            message.Subject = content;

            await _client.SendMailAsync(message);
        }
    }

And in Startup class:

services.AddSingleton<IEmailSenderService, EmailSenderService>();

Is built-in DI container enough?

This is an important question to ask. Microsoft did a great job in developing a Dependency Injection container, but there are several great solutions out there that are ready to use. Actually, Microsoft lists them on an official documentation page: https://docs.microsoft.com/en-gb/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-3.1#default-service-container-replacement

So what are popular DI containers you might try out?

  • Autofac
  • Lamar
  • Scrutor

And those are only a few, there are more. The important thing is how they are different from a built-in container. The obvious answer is that they offer more. So what Microsofts built-in container doesn’t offer?

  • property injection
  • custom lifetime management
  • lazy initialization
  • auto initialization based on name

I must admit, that I miss the last one the most. In SimpleInjector for .Net Core 2.1 it was possible to register dependencies if only they follow naming convention with an interface having the same name as implementing class, with preceding ‘I’. There was no need to write registration for 90% of cases. 

So what I would use?

I would use a built-in container, whenever I don’t need any specific features. Without 3rd party nuget packages code is cleaner and easier to understand. .Net Core 3 doest pretty good job and you probably won’t need anything else. 

Hope you enjoyed this post, you can have a look at the code posted here on my Github:

https://github.com/mikuam/TicketStore

ASP.Net Core 3 – pass parameters to actions

Passing parameters to actions is an essential part of building RESTful Web API. .Net Core offers multiple ways to pass parameters to methods, that represent your endpoints. Let’s see what they are.

Pass parameter as a part of an url

When passing a parameter in a url, you need to define a routing that would contain a parameter. Let’s have a look a the example:

    [Route("{daysForward}")]
    [HttpGet]
    public IActionResult Get(int daysForward)
    {
        var rng = new Random();
        return new JsonResult(new WeatherForecast
        {
            Date = DateTime.Now.AddDays(daysForward),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        });
    }

 

This method returns a WeatherForecast for a single day in the future. DaysForward parameter represents how many days in advance weather forecast should be returned for. Notice that daysForward is a part of the routing, so a valid url to this endpoint will look like:

GET: weatherForecast/3

We can also use [FromRoute] attribute before variable type, but it will also work the same way by default.

   public IActionResult Get([FromRoute] int daysForward)

Pass parameter in a query string

This is a vary common method for passing additional parameters, because it does not require for us to change routing, so it is also backward compatible. It’s important if we were to change an existing solution.

Let’s look at a different method, that would return a collection of weather worecasts with a sorting option.

[HttpGet]
    public IEnumerable<WeatherForecast> Get([FromQuery]bool sortByTemperature = false)
    {
        var rng = new Random();
        var forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        });

        if (sortByTemperature)
        {
            forecasts = forecasts.OrderByDescending(f => f.TemperatureC);
        }

        return forecasts;
    }

In this example we pass on sortByTemperature parameter which is optional. Notice that we use [FromQuery] attribute to indicate, that it’s a variable taken from query string. A url to this endpoint would look like this:

GET: weatherForecast?sortByTemperature=true

You can put many prameters like this:

GET: weatherForecast?key1=value1&key2=value2&key3=value3

Remember, that url needs to be encoded properly to work right. If you were to pass a parameter like this:

https://www.michalbialecki.com/?name=Michał Białecki

It will need to be encoded into:

https://www.michalbialecki.com/?name=Micha%C5%82%20Bia%C5%82ecki

Pass parameters with headers

Passing parameters in a request headers are less popular, but also widely used. It doesn’t show in a url, so it’s less noticeable by the user. A common scenario for passing parameters in a header would be providing credentials or a parent request id to enable multi-application tracking. Let’s have a look at this example:

    [HttpPost]
    public IActionResult Post([FromHeader] string parentRequestId)
    {
        Console.WriteLine($"Got a header with parentRequestId: {parentRequestId}!");
        return new AcceptedResult();
    }

In order to send a POST request, we would need to use some kind of a tool, I’ll use Postman:

Here you see that I specified headers and parentRequestId is one of them.

Pass parameters in a request body

The most common way to pass the data is to include it in a request body. We can add a header Content-Type with value application/json and inform the receiver how to interpret this body. Let’s have a look at our example:

    [HttpPost]
    public IActionResult Post([FromBody] WeatherForecast forecast)
    {
        Console.WriteLine($"Got a forecast for data: {forecast.Date}!");
        return new AcceptedResult();
    }

We use [FromBody] attribute to indicate, that forecast will be taken from request body. In .Net Core 3 we don’t need and serialize to deserialize json body to WeatherForecast object, it will work automatically. To send POST request, let’s use Postman once again:

Have in mind, that size of the request body is limited by the server. It can be anywhere between 1MB to 2GB. In ASP.Net Core maximum request body size is around 28MB, but that can be changed. What if I would like to send bigger files than that, over 2GB? Then you should look into sending content as a stream or sending it in chunks.

Pass parameters in a form

Sending content in a form is not very common, but it is the best solution if you want to upload a file. Let’s have a look at the example:

    [HttpPost]
    public IActionResult SaveFile([FromForm] string fileName, [FromForm] IFormFile file)
    {
        Console.WriteLine($"Got a file with name: {fileName} and size: {file.Length}");
        return new AcceptedResult();
    }

This method doesn’t really send a file, but it will successfully receive a file from the request. The interface IFormFile is used specifically for handling a file.

When sending a request we need to set Content-Type to application/x-www-form-urlencoded and it the Body part, we need to choose a file:

Let’s see what do we get when we debug this code:

And the file is correctly read. An interesting fact is, that with IFormFile we get not only binary data but also a file type and name. So you might ask why I send a file name separately? This is because you might want to name file differently on the server, then the one you are sending.

Hope you enjoyed this post, you can have a look at the code posted here on my Github:

https://github.com/mikuam/TicketStore