Forem: Chinonso Ikewelugo

Understanding Sorting Algorithms (with Examples in Java)

Chinonso Ikewelugo — Fri, 17 Jan 2025 16:36:57 +0000

Sorting is used to rearrange elements in a list in a specified order. For instance, we might want to sort this list in ascending order:

A sorting algorithm is used to carry out the process of sorting.

Different Sorting Algorithms

There are several different sorting algorithms in use today. A few we will look at are:

Efficiency of Sorting Algorithms

We can determine the efficiency of sorting algorithms by checking their time and space complexities.

Time Complexity:

This refers to the amount of time taken for the algorithm its execution with respect to the input. It can be represented in many forms, but the most common is using the Big O notation.

Space Complexity:

This refers to the amount of memory used by the algorithm to complete its execution. It can also be represented using the Big O notation.

Understanding Quick Sort Algorithm (with Examples in Java)

Chinonso Ikewelugo — Fri, 17 Jan 2025 16:15:45 +0000

Quick Sort is a popular sorting algorithm based on the Divide-and-Conquer approach, in which a problem is divided into smaller subproblems and solved individually, then the solutions to the individual subproblems are combined to get the final solution. In Quick Sort, the array is divided by selecting a partition element, the position from which we will divide the array. Before we divide the array, the position of the partition element is rearranged in such a way that it is placed before elements greater than it and after elements smaller than it. The left and right subarrays are further recursively divided in this manner until we reach a case where a subarray contains only one element. At this point, the array is already sorted.

Working of Quick Sort

Let's say we want to sort this array in ascending order.

Step 1

We will start by selecting the pivot element. We can select the last element as the pivot:

Step 2

Here we position the pivot element before elements greater than it and after elements smaller than it. To do that we will loop through the array and compare the pivot with all the elements preceding it.
If we find an element greater than the pivot, we create a second pointer for it:

If we find an element smaller than the pivot, we swap it with the second pointer:

The process is repeated to set the next greater element as the second pointer, and swap it with an element smaller than the pivot if found:

We will continue until we get to the end of the array:

Once we are done comparing the elements and the elements smaller than the pivot have been moved to the right, we then swap the pivot with the second pointer:

Step 3

Here we will divide the array according to the partition index. If we can represent the array as arr[start..end], then to divide the array by the partition we can get the left subarray as arr[start..partitionIndex-1] and the right subarray as arr[partitionIndex+1..end].

The subarrays are further divided in this way until each subarray contains only a single element:

At this point, the array is already sorted.

Implementation of Quick Sort

public class QuickSortTest {
    public static void main(String[] args){
        int[] arr = {8, 6, 2, 3, 9, 4};
        System.out.println("Unsorted array: " + Arrays.toString(arr));
        quickSort(arr, 0, arr.length-1);
        System.out.println("Sorted array: " + Arrays.toString(arr));
    }

    public static int partition(int[] arr, int start, int end){
        // set the last element as the pivot
        int pivot = arr[end];
        // create a pointer for the next greater element
        int secondPointer = start-1;

        // move smaller elements to the left of the pivot
        for (int i = start; i < end; i++) {
            if(arr[i] < pivot){
                secondPointer++;
                int temp = arr[i];
                arr[i] = arr[secondPointer];
                arr[secondPointer] = temp;
            }
        }

        // swap the pivot with the second pointer
        secondPointer++;
        int temp = arr[end];
        arr[end] = arr[secondPointer];
        arr[secondPointer] = temp;

        // return the partition position
        return secondPointer;
    }

    public static void quickSort(int[] arr, int start, int end){
        if(start < end){
            // divide the array into two sub arrays and get the partition index
            int partition = partition(arr, start, end);

            // recursively sort the two sub arrays
            quickSort(arr, start, partition - 1);
            quickSort(arr, partition + 1, end);
        }
    }
}

Let's look at the code above.

The quickSort Method

In the quickSort method, we first call the partition method to divide the array into two subarrays. We then recursively call quickSort on the left and right subarrays. This process continues until we reach a base condition where all subarrays contain only one element. At this point, the array is already sorted.

The partition Method

This is where we divide the into two subarrays. We start by setting pointers for the pivot and the next greater element. Then we loop through the array and move elements smaller than the pivot to the left. After that, we swap the pivot with the second pointer and return the partition position.

Running the code above will print the following output to the console:

Unsorted array: [8, 6, 2, 3, 9, 4]
Sorted array: [2, 3, 4, 6, 8, 9]

Time Complexity:

Best Case (O(n log n)):

The best case occurs when the pivot divides the array into two nearly equal halves at each step.

Average Case (O(n log n)):

In the average case, the pivot divides the array into two unequal parts, but the depth of recursion and the number of comparisons remain proportional to n log n.

Worst Case (O(n²)):

The worst case occurs when the pivot consistently divides the array into highly uneven parts (e.g., one part has one element, and the other has n−1 elements). This happens when the pivot is the highest or lowest element, for example when sorting a reverse-order array, with poor pivot selection.

Space Complexity (O(log n)):

Quick Sort is generally implemented in-place, requiring no additional arrays.

Understanding Merge Sort Algorithm (with Examples in Java)

Chinonso Ikewelugo — Fri, 17 Jan 2025 16:15:14 +0000

Merge Sort is one of the most popular sorting algorithms. Many programming languages use either purely Merge Sort or a hybrid algorithm involving Merge Sort for sorting. It is based on the Divide-and-Conquer approach, in which a problem is divided into smaller subproblems and solved individually, then the solutions to the individual subproblems are combined to get the final solution. In Merge Sort, the provided list is recursively divided into two halves, and each half is sorted. Each sorted half is then combined to give a sorted list.

Working of Merge Sort

Suppose we want to sort an array arr. Using the Divide-and-Conquer approach and solving recursively:

Divide

In the divide step, we will recursively divide into halves until it can no longer be divided; until there is only one element in a subarray. Let us call the 0th index of the array start and the last index end. So our array can be represented as arr[start..end]. Suppose the midpoint of the array is mid, then we can divide the array into two halves, arr[start..mid, mid+1..end].

Conquer

Once the array has been divided until we have two subarrays with only one element in each, each subarray is considered to be sorted. We can now merge two subarrays in sorted order. This process continues until all subarrays have been merged.

Let's say we want to sort this array in ascending order.

This is an illustration of the process we would go through if we used Merge Sort.

Implementation of Merge Sort

public class MergeSortTest {
    public static void main(String[] args){
        int[] arr = {8, 2, 6, 4, 9, 1};
        System.out.println("Unsorted array: " + Arrays.toString(arr));
        mergeSort(arr, 0, arr.length-1);
        System.out.println("Sorted array: " + Arrays.toString(arr));
    }

    static void merge (int arr[], int start, int mid, int end){
        // create backups of the two subarrays
        int[] left = new int[(mid - start) + 1];
        int[] right = new int[end - mid];

        // copy values into left array
        for(int i = 0; i < left.length; i++){
            left[i] = arr[i+start];
        }

        // copy values into right array
        for(int i = 0; i < right.length; i++){
            right[i] = arr[i+mid+1];
        }

        // maintain pointers to track the current index of the
        // left and right subarrays, and the main array
        int j = start, lIndex = 0, rIndex = 0;

        // set the values from start to end in sorted order, as long
        // as there are still elements in both the left and right subarrays
        while(lIndex < left.length && rIndex < right.length){
            if(left[lIndex] <= right[rIndex]){
                arr[j] = left[lIndex];
                lIndex++;
            }else {
                arr[j] = right[rIndex];
                rIndex++;
            }

            j++;
        }

        // add leftover values from left subarray if any
        while (lIndex < left.length) {
            arr[j] = left[lIndex];
            lIndex++;
            j++;
        }

        // add leftover values from right subarray if any
        while (rIndex < right.length) {
            arr[j] = right[rIndex];
            rIndex++;
            j++;
        }
    }

    static void mergeSort(int arr[], int start, int end){
        // base condition; will execute only if start is less than end,
        // i.e. there's more than element in the array/subarray
        if(start < end){
            // find the midpoint of the array
            int mid = (start + end) / 2;

            // divide further since we have not reached the base case
            mergeSort(arr, start, mid);
            mergeSort(arr, mid + 1, end);

            // merge the two sorted sections
            merge(arr, start, mid, end);
        }
    }
}

Let's look at the code above.

The mergeSort Method

In the mergeSort method, we find the midpoint of the array, and recursively call mergeSort to sort the left and right subarrays. The code in mergeSort will run until the base condition is met, that is until the subarray contains only one element.

The merge Method

This is the most important part of the merge sort algorithm. In addition to the main array, it takes input indicating the positions of the two sorted subarrays. By knowing start, mid and end, we can represent the left subarray as arr[start..mid] and the right as arr[mid+1..end].
In the merge method, we try to set the values in the main array in sorted order by combining the values from the two subarrays. We start by creating copies of the left and right subarrays. We then create pointers to track the current index of the left and right subarrays, as well as the main array, and loop through the array to set the values from start to end by adding values from the left and right subarrays in sorted order. For instance, the process to merge these two sorted arrays would look like this:

Running the code above will print the following output to the console:

Unsorted array: [8, 2, 6, 4, 9, 1]
Sorted array: [1, 2, 4, 6, 8, 9]

Complexity of Merge Sort

Time Complexity (O(n log n)):

Merge Sort has a time complexity of O(n log n) in all cases, because it always follows the same divide-and-conquer approach whether the array is already sorted or not.

Space Complexity (O(n)):

Merge Sort requires additional memory for temporary arrays used during the merge operation.

Understanding Insertion Sort Algorithm (with Examples in Java)

Chinonso Ikewelugo — Fri, 17 Jan 2025 16:14:38 +0000

Insertion sort is a sorting algorithm that works by iteratively inserting each element in an unsorted list into its correct position in a sorted portion of the list. This algorithm is very similar to sorting cards in your hand. We assume that the first card is already sorted, then we take the second card and place it to the right of the sorted card if it is smaller, or to the left if it is bigger. We will continue this process for the remaining cards.

Working of Insertion Sort

Let's say we want to sort this array in ascending order.

First Iteration

We assume that the first element is already sorted, so we will start the iteration from the second element.

We will compare the element, 2, with the element in the sorted portion of the array, 8. Since 2 is less than 8, we move 8 to the right and 2 to the left.

Second Iteration

We will compare the current element, 6, with the elements in the sorted portion of the array, 2 and 8. Since 6 is less than 8, we move 8 to the right and 6 to the left. 6 is greater than 2 so it is now in its correct position.

This process is repeated until the entire array is sorted.

Implementation of Insertion Sort

public class InsertionSortTest {
    public static void main(String[] args) {
        int[] arr = {8, 2, 6, 4, 9, 1};
        System.out.println("Unsorted array: " + Arrays.toString(arr));
        insertionSort(arr);
        System.out.println("Sorted array: " + Arrays.toString(arr));
    }

    public static void insertionSort(int[] arr){
        // loop through array starting from second element
        for (int i = 1; i < arr.length; i++) {
            int key = arr[i]; // set element at i as key

            // loop backwards through sorted elements to find
            // where to insert the key element
            int j = i-1;

            while (j >= 0 && key < arr[j]) {
                // move element greater than key to the right
                arr[j+1] = arr[j];
                j--;
            }

            arr[j+1] = key;
        }
    }
}

In the code above, we iterate through the array starting from the second element. Inside the first loop, we set the current element as the key, and then we compare it with each element in the sorted portion of the array by looping backward from i-1 until we find its correct position.
For example, in the second iteration, when i = 2:

We set the current element as the key:

In the while block, we iterate backward through the sorted section of the array. In the first iteration of while loop, j = 1 (i-1). If the current element in the sorted section is greater than the key, we move it to the right by saying arr[j+1] = arr[j]:

In the second iteration, j = 0. The key 6 is greater than the current element 2, so it does not satisfy the second condition for the while loop and we break out of the while loop.
After breaking out of the loop, we insert the key after the element smaller than it by saying arr[j=1] = key.

The key is now in its correct position and we can move on to the next iteration.

Running the code above will print the following output to the console:

Unsorted array: [8, 2, 6, 4, 9, 1]
Sorted array: [1, 2, 4, 6, 8, 9]

Complexity of Insertion Sort

Time Complexity:

Best Case (O(n)):

The best case is when the array is already sorted. The algorithm performs n−1 comparisons (one for each element except the first) and no shifts. Therefore, the time complexity is O(n).

Average Case (O(n²)):

This occurs when the array's elements are arranged randomly. For each insertion, every element is compared with all previously inserted elements.

Worst Case (O(n²)):

The worst case is when the array is sorted in reverse order. Each element must be compared with all previous elements and shifted.

Space Complexity O(1):

Insertion Sort is an in-place algorithm and requires no additional memory other than a few variables for looping and temporary storage during shifts.

Conclusion

Insertion Sort has an O(n²) time complexity in the average and worst cases. It is unsuitable when working with large datasets of randomly arranged data due to its high time complexity. Use Insertion Sort when working with small datasets, or when the list is nearly sorted.

Understanding Selection Sort Algorithm (with Examples in Java)

Chinonso Ikewelugo — Fri, 17 Jan 2025 16:11:56 +0000

In Selection Sort, we iterate through an unsorted list, and on each iteration, the smallest (or largest, if we are sorting in descending order) element is selected and placed at the beginning of the list. This process goes on until all the elements in the list are sorted.

Working of Selection Sort

Let's say we want to sort this array in ascending order

First Iteration

The goal of the iteration is to place the smallest element in the unsorted array at the beginning. We start by setting the first element in the unsorted list as the minimum.

We then compare the minimum with the second element, and set the second element as the minimum if it is smaller.

This is repeated for the remaining elements and eventually, the smallest element is set as minimum.

We then swap the minimum element with the element at the beginning of the unsorted list.

Elements that have moved to their correct position are said to be sorted. In subsequent iterations, we will only compare the unsorted elements.

Subsequent Iterations

This process is repeated for all iterations until the array is sorted.

We iterate through the array n-1 times, where n is the length of the array. That is, since our array has six elements, we iterate through the array only five times. This is because, after the fifth iteration, five elements have been placed in their correct position, therefore the final unsorted element is considered sorted. After all iterations, we will have a sorted array.

Implementation of Selection Sort

public class SelectionSortTest {
    public static void main(String[] args) {
        int[] arr = {8, 2, 6, 4, 9, 1};
        System.out.println("Unsorted array: " + Arrays.toString(arr));
        selectionSort(arr);
        System.out.println("Sorted array: " + Arrays.toString(arr));
    }

    public static void selectionSort(int[] arr){
        int size = arr.length;

        // loop through array size-1 times
        for (int i = 0; i < size-1; i++) {
            int minIndex = i; // set the current index as the minimum

            // loop through the unsorted elements
            for (int j = i+1; j < size; j++) {
                if(arr[j] < arr[minIndex]) minIndex = j;
            }

            // place the minimum element at the current index
            if (minIndex != i){
                int temp = arr[i];
                arr[i] = arr[minIndex];
                arr[minIndex] = temp;
            }
        }
    }
}

Running this code will print the following output to the console:

Unsorted array: [8, 2, 6, 4, 9, 1]
Sorted array: [1, 2, 4, 6, 8, 9]

Complexity of Selection Sort

Time Complexity:

Best Case (O(n²)):

Selection Sort always scans the entire unsorted portion of the array to find the minimum element in each pass, whether the array is already sorted or not.

Average Case (O(n²)):

Like the best case, the number of comparisons does not depend on the initial ordering.

Worst Case (O(n²)):

Similar to the average and best case, the number of comparisons does not depend on the initial ordering.

Space Complexity O(1):

Selection Sort is an in-place sorting algorithm, that is, it does not require any extra memory proportional to the size of the input array.

Conclusion

Selection Sort has a time complexity of O(n²) in all cases. It is not suitable to use when working with large datasets due to its high time complexity. Use Selection Sort when working with small datasets, or when you are not concerned with complexity.

Understanding Bubble Sort Algorithm (with Examples in Java)

Chinonso Ikewelugo — Fri, 17 Jan 2025 16:09:31 +0000

Bubble Sort is the simplest sorting algorithm. It works by repeatedly comparing adjacent elements and swapping them if they are not in the correct order. For example, if the sorting order is ascending, adjacent elements are compared, and the greater element is placed on the right. In each iteration, we compare only the unsorted elements, and the largest element is placed at the last position of the unsorted elements in the array.

The algorithm is aptly named Bubble Sort, because elements move to the right of the array on each iteration in the order specified, much like air bubbles in water rise to the surface.

Working of Bubble Sort

Let's say we want to sort this array in ascending order

First Iteration

In the first iteration, we are trying to move the largest element to the end of the array. So, we will repeatedly compare adjacent elements, and swap them if they are out of order.

Elements that have moved to their correct position are said to be sorted.

Subsequent Iterations

This process is repeated for all iterations until the array is sorted. In each iteration, we only compare the unsorted elements, since the sorted elements are already in the correct order.

We iterate through the array n-1 times, where n is the length of the array. That is, since our array has six elements, we iterate through the array only five times. This is because, after the fifth iteration, five elements have been placed in their correct position, therefore the final unsorted element is considered sorted. After all iterations, we will have a sorted array.

Implementation of Bubble Sort

public class BubbleSortTest {
    public static void main(String[] args) {
        int[] arr = {8, 2, 6, 4, 9, 1};
        System.out.println("Unsorted array: " + Arrays.toString(arr));
        bubbleSort(arr);
        System.out.println("Sorted array: " + Arrays.toString(arr));
    }

    public static void bubbleSort(int[] arr) {
        int size = arr.length;

        // loop through array size-1 times
        for (int i = 0; i < size - 1; i++) {
            // loop until end of unsorted elements
            for (int j = 0; j < size - i - 1; j++) {
                // swap left and right elements if left is greater
                if (arr[j] > arr[j + 1]) {
                    int temp = arr[j];
                    arr[j] = arr[j + 1];
                    arr[j + 1] = temp;
                }
            }
        }
    }
}

Running this code will print the following output to the console:

Unsorted array: [8, 2, 6, 4, 9, 1]
Sorted array: [1, 2, 4, 6, 8, 9]

In this implementation of Bubble Sort, we will iterate through the array each time even if it is already sorted. We can optimize the code further to stop sorting once the array is already sorted.

Optimized Bubble Sort

public static void bubbleSortOptimised(int[] arr){
        int size = arr.length;

        // loop through array size-1 times
        for (int i = 0; i < size - 1; i++) {
            boolean swapped = false; // track swapping

            // loop until end of unsorted elements
            for (int j = 0; j < size - i - 1; j++) {
                // swap left and right elements if left is greater
                if(arr[j] > arr[j+1]){
                    int temp = arr[j];
                    arr[j] = arr[j+1];
                    arr[j+1] = temp;

                    swapped = true;
                }
            }

            // if there was no swap, then the array is already sorted
            if(!swapped) break;
        }
    }

With this implementation, if we are trying to sort an already sorted array, we will iterate only once and stop once no sorting is done.

Complexity of Bubble Sort

Time Complexity:

Best Case (O(n)):

The best case is when the input array is already sorted. The algorithm iterates through the array only once to check if it is sorted and performs no swaps.

Average Case (O(n²)):

This is when the input array elements are in random order. The algorithm must make multiple iterations and perform swaps to sort the array.

Worst Case (O(n²)):

The worst case is when the input array is sorted in reverse order. The algorithm makes n-1 iterations and performs the maximum number of swaps.

Space Complexity O(1):

Bubble Sort is an in-place sorting algorithm, that is, it does not require any extra memory proportional to the size of the input array.

Conclusion

Bubble Sort is a simple-to-understand and implement algorithm. However, it is not suitable to use Bubble Sort when working with large datasets due to its high time complexity. Use Bubble Sort when working with small datasets, or when you are not concerned with complexity.

Logging in .NET 8 with Serilog and Seq

Chinonso Ikewelugo — Sat, 06 Apr 2024 12:56:33 +0000

Introduction

When developing locally, we can easily use breakpoints and debugging to inspect our code and see how it behaves. This is not possible when we deploy the application to another environment, say staging or production. When we don't have access to debug locally, we can depend on logs.
Logging is a means by which we keep track of what happens in our applications. We can write logs for informational purposes, or to trace errors in our application.

Logging with Serilog

Serilog is a simple-to-use diagnostic logging library for .NET applications. It runs on all recent .NET versions and can be configured to log to files, the console, and other external providers.

Installing and Configuring Serilog

We can install Serilog via the command line or the NuGet package manager.

dotnet add package Serilog

Once installed, we can setup Serilog at application startup, typically in the program.cs, using the Serilog.Log static class:

using Serilog;

Log.Logger = new LoggerConfiguration()
    .CreateLogger();

Our configured logger currently does not log to any location. To see our logs we have to configure sinks. Let's see what sinks are.

Serilog Sinks

Serilog uses sinks to record events to an external representation. When configuring Serilog, we have to specify our desired sinks, if not our events do not get logged anywhere. Serilog sinks are distributed via NuGet. Examples of available sinks include the Console sink, which prints the log data to the console, and the File sink, which writes log events to a file. We can also add these to our application via the command line or NuGet package manager.

dotnet add package Serilog.Sinks.Console
dotnet add package Serilog.Sinks.File

We can now configure our logger to write to the desired sinks:

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .WriteTo.File("log.txt",
        rollingInterval: RollingInterval.Day)
    .CreateLogger();

WriteTo.Console() specifies that log events should be written to the console.
To use WriteTo.File(), we have to specify the location of the log file. We can also provide some additional parameters like the rollingInterval. Here, we are specifying that a new log file will be created each day.

Minimum Level

Serilog provides six log levels:
Verbose: This is the noisiest level, and logs all trace events. This level is not commonly enabled in production environments.
Debug: This level is used to log the application's internal events that are not necessarily observable from outside.
Information: This level is used to log information about the normal application processes.
Warning: This level is used to log warnings about events that are outside of the application's normal behavior.
Error: This is used to log events of broken functionalities in the application. This requires immediate attention.
Fatal: This is the most critical level. It is used for logging events which can cause the application to crash. Fatal events also require immediate attention.

We can specify the minimum level at which we want to capture events while configuring our logger.

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .WriteTo.Console()
    .WriteTo.File("log.txt",
        rollingInterval: RollingInterval.Day,
        rollOnFileSizeLimit: true)
    .CreateLogger();

If not specified, Serilog uses Information as the minimum level by default.

We can write log events by using methods of the Log class that match the event level. For example we can write a warning event like this:

Log.Warning("Unable to load some services");

Using the Logger in Application Classes

The easiest way to use the logger in our application classes is via the global Log class. For example:

[Route("api/[controller]")]
[ApiController]
public class TestController : ControllerBase
{ 
    [HttpPost("test-logger")]
    public IActionResult TestLogger()
    {
        Log.Information("This log is from the global Log class");
        return Ok();
    }
}

When we run our application and call the test-logger endpoint, we see this in the console:

Another way we can make use of the logger is by injecting it into the class as an ILogger. We first have to configure Serilog as our logging provider. To do this we have to install the Serilog.AspNetCore NuGet package.

dotnet add package Serilog.AspNetCore

NOTE: Serilog.AspNetCore has Serilog and a few sinks as dependencies. So when you install Serilog.AspNetCore, you don't have to install Serilog, Serilog.Sinks.Console and Serilog.Sinks.File.

After installing the package, we can call UseSerilog() on the Host object of the application builder in our program.cs to configure Serilog as our logging provider and pass in the log object:

builder.Host.UseSerilog(Log.Logger);

We can now make use of the logger in our application class by injecting the ILogger interface in the constructor:

[Route("api/[controller]")]
[ApiController]
public class TestController : ControllerBase
{ 
    private readonly ILogger<TestController> _logger;

    public TestController(ILogger<TestController> logger)
    {
        _logger = logger;
    }

    [HttpPost("test-logger")]
    public IActionResult TestLogger()
    {
        _logger.Information("This log is from the injected ILogger");
        return Ok();
    }
}

When we run our application and call the test-logger endpoint, we see this in the console:

Writing Logs to Seq

Seq is a self-hosted search and analysis server for structured logs. Events are captured as fully structured JSON data and Seq makes it easy to search and filter through with various parameters. This provides a more efficient way to access and make sense of our logs than writing to files.
Seq can be installed on your local machine or on a Windows or Linux server.

Installing Seq Locally

You can download Seq .msi from https://datalust.co/download, and follow the default installation guide to install it on your local machine.

You can choose to start the Seq service once the installer has finished copying the files. This will open the Seq Service Administration dialog for the initial setup. You will be prompted to provide the desired location to store Seq's data files and a URL to host Seq's user interface and HTTP API. You can leave these as the defaults. You can also optionally set an administrator username and password.
When you're done with the setup you can open the Seq UI by visiting the default URL, http://localhost:5341, or the one you configured.

After logging in you can access the Seq UI

We are now ready to configure our logger to write to Seq. To do this we have to install the Seq sink.

dotnet add package Serilog.Sinks.Seq

In our logger configuration we can now write to Seq and provide the Seq URL:

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .WriteTo.Seq("http://localhost:5341")
    .CreateLogger();

Log.Information("Starting up application");

Let us check the Seq UI again to see if our informational log appears:

Conclusion

Logging is an important part of our applications. It can save time in figuring out production issues and also provide necessary information when monitoring. We have seen how to combine Serilog logging with a powerful search and analysis server like Seq.
You can get the sample code for this tutorial here.

To learn more about Serilog, you can visit the documentation on their GitHub project.
To learn more about Seq, you can visit the documentation on their website.

Reading Configuration Values in Your ASP.NET Application

Chinonso Ikewelugo — Sat, 23 Mar 2024 12:00:28 +0000

Prerequisites

Some knowledge of C# and ASP.NET

Introduction

When building our applications, we usually have some constants that are either used to handle the application setup, or are part of our application logic. We cannot necessarily hard-code these values where needed, because a change to such a value would require changes in all the files where the value is used. This is not very efficient or neat. The better way is to store these values in a configuration file, such as the appsettings.json file in our ASP.NET application. We can then read the values in our application, and any changes required would be made in just one location, the configuration file.

Reading Configuration Values from appsettings.json

So, how do we read configuration values from our appsettings.json? We will look at two ways we can do this.

The first is by making use of the configuration object directly. In .NET 5 and below, the configuration object is an instance of ConfigurationRoot, and is present in the Startup.cs by injecting the IConfinguration interface in the constructor.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;

        decimal interestRate = configuration.GetSection("LoanSettings").GetValue<decimal>("InterestRate");
    }

    public IConfiguration Configuration { get; }
}

In .NET 6 and above, the configuration object is an instance of ConfigurationManager, and is a property of the the application builder. So it can be accessed like so in the program.cs.

var builder = WebApplication.CreateBuilder(args);
var configuration = builder.Configuration;

We can then use a number of methods on the configuration object to read our values. Say we had our appsettings.json structured like this:

{
  "EnableLoans": true,
  "LoanSettings": {
    "InterestRate": 0.07,
    "DefaultLoanTenure": 6
  }
}

We can access the InterestRate value by calling GetSection on the configuration object, and chaining GetValue to it:

decimal interestRate = configuration.GetSection("LoanSettings").GetValue<decimal>("InterestRate");

GetSection retrieves the section with the specified key, and GetValue retrieves the value with the specified key inside that section and converts it to the type specified.

To access our configuration values outside of the Program.cs or Startup.cs, we add the IConfiguration to the constructor of the classes in which we need the configurations.

 public class LoanService
 {
    private readonly IConfiguration _configuration;

    public LoanService(IConfiguration configuration)
    {
        _configuration = configuration;
    }
 }

We can now make use of the configuration variable in the same way.

decimal interestRate = configuration.GetSection("LoanSettings").GetValue<decimal>("InterestRate");

The problem with this method is that we're loading our application's entire configuration each time we need it, just to access some specific configurations. So, this is not very performance-friendly.

A better way would be to fetch only what we need and use it in the class. We can achieve this by creating a model for the section in our appsettings.json, with properties matching the names and types of the keys we have configured. We can then bind the configurations in the section to the model on application startup.

So, we could have a class matching the LoanSettings section of our appsettings.json like this:

public class LoanSettings
{
    public decimal InterestRate { get; set; }
    public decimal DefaultLoanTenure { get; set; }
}

We can then bind this model to our LoanSettings configuration by calling the Configure method on our service collection.

builder.Services.Configure<LoanSettings>(configuration.GetSection("LoanSettings"));

We can now use the configured instance of LoanSettings like this:

public class LoanService
{
    private readonly IOptions<LoanSettings> _loanSettings;

    public LoanService(IOptions<LoanSettings> loanSettings)
    {
        _loanSettings = loanSettings;
    }
}

IOptions is used to retrieve configured instances of LoanSettings. The Value property of the IOptions holds the LoanSettings instance.

decimal interestRate = _loanSettings.Value.InterestRate;

We can alternatively inject the LoanSettings directly in our class constructor without wrapping it in IOptions, by adding it as a service after calling Configure on the service collection.

builder.Services.Configure<LoanSettings>(configuration.GetSection("LoanSettings"));
builder.Services.AddScoped(config => config.GetRequiredService<IOptions<LoanSettings>>().Value);

public class LoanService
{
    private readonly LoanSettings _loanSettings;

    public LoanService(LoanSettings loanSettings)
    {
        _loanSettings = loanSettings;
    }
}

We can now access the LoanSettings object directly:

decimal interestRate = _loanSettings.InterestRate;

Conclusion

This is how we access and make use of configuration values in our application safely and efficiently.

Background Job Scheduling in .NET using Hangfire

Chinonso Ikewelugo — Wed, 31 May 2023 08:06:08 +0000

Introduction

In this article we will look at how to use Hangfire to schedule background jobs in ASP.NET.

Prerequisites

Some knowledge of C# and ASP.NET
SQL Server
SQL Server Management Studio

What is Hangfire?

Hangfire is an opensource framework that helps to efficiently create, process, and manage background tasks in an ASP.NET application.

Why Hangfire

We might have tasks that we want to be performed outside the request processing pipeline, tasks that need to run after some time, or tasks that need to be run at specific intervals and do not require user interaction. For example, sending bulk emails, processing reports, searching for and retrying failed transactions, etc. Hangfire can help us with all these scenarios, and does this efficiently, as we will soon see.

Hangfire Overview

Broadly speaking, the Hangfire library consists of 3 main components: client, storage and server.

Client

The Hangfire client is used to create the background jobs. You can create various types of background jobs using Hangfire:

Fire-and-Forget Jobs: These are executed only once almost immediately after creation.

Delayed Jobs: These are tasks that are executed after a set timespan.

Recurring Jobs: These are jobs that are executed at defined intervals, eg hourly, daily, etc.

Continuations Jobs: These are jobs that are chained to other jobs and executed only when the parent job is done executing.

Background jobs in Hangfire can be created using regular static or instance method invocations. Here's an example of creating a fire-and-forget job using both techniques.

// 1)
var client = new BackgroundJobClient();
client.Enqueue(() => Console.WriteLine("Hello World"));

// 2)
BackgroundJob.Enqueue(() => Console.WriteLine("Hello World"));

Storage

After a job is created using Hangfire, no data is kept in the application's memory. All details relating to the background job's processing, like types, method names, arguments, etc. are serialized and placed into a persistent storage. Persistence helps to keep your background jobs safe in the case of exceptions, application restarts or server reboots. In any of these instances, your background jobs will be retried automatically after restart.

Different storage backends are supported by Hangfire, eg SQL and Redis.

Server

Background jobs are processed by the Hangfire server. It does this by querying the storage. The Hangfire server is basically a set of dedicated background threads that listen to the storage for new background jobs, and processes them by deserializing the types, method names and arguments.

The Hangfire Dashboard

Another good thing about Hangfire is that it provides a graphical interface we can use to visualize and obtain information about our background jobs. We can see information relating to scheduled, succeeded or failed jobs on the Hangfire dashboard. We can also manually retry jobs from the dashboard.

Demo - Hangfire Installation and Configuration

We will create a simple ASP.NET Web Api project and demonstrate how to install and configure Hangfire. We will be using SQL Server as our Hangfire storage.
Our testing scenario will involve creating 3 endpoints to demonstrate 3 of the common jobs we can create using Hangfire.

a) A user signs up on our ecommerce app and we create a fire-and-forget job to send the user a welcome mail.
b) A user adds an item to their cart and we create a scheduled job to run after 5 minutes and send the user a reminder if the order has not been completed.
c) We call an endpoint to create a recurring job that runs hourly and checks for orders pending delivery.

Step 1

Create an ASP.NET Web API project

Step 2

Set the project and solution names

Step 3

Select your target framework. I'm going with .NET 5 because I am running VS 19.

Step 4

Install the following NuGet packages using either the Package Manager Console or the UI window.

Hangfire
Hangfire.SqlServer
Microsoft.SqlClient

Note: We will also install Swashbuckle.AspNetCore to enable Swagger

Step 5

Configure Hangfire in Startup.cs

using Hangfire;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace HangfireDemo
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            services.AddHangfire(options => options.UseSqlServerStorage("Server=.;Initial Catalog=HangfireDB; Integrated Security=true;TrustServerCertificate=True")));
            services.AddHangfireServer();
            services.AddSwaggerGen();
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            app.UseSwagger();
            app.UseSwaggerUI();

            app.UseHttpsRedirection();

            app.UseHangfireDashboard();

            app.UseRouting();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Here, in the ConfigureServices method we call the AddHangfire extension method and configure it to use SqlServer for storage by calling the UseSqlServerStorage extension method. We also call the AddHangfireServer extension method to enable Hangfire server.
In the Configure method, we add the UseHangfireDashboard middleware to the pipeline to enable the Hangfire dashboard. The default path for the Hangfire dashboard is https://localhost:port/hangfire.

Step 6

Create the database. Open SSMS and create the database to be used as the Hangfire storage.

Step 7

Create HomeController and add endpoints.

using Hangfire;
using Microsoft.AspNetCore.Mvc;
using System;

namespace HangfireDemo.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class HomeController : ControllerBase
    {
        [HttpPost("register")]
        public IActionResult Register()
        {
            // register user

            // create fire-and-forget job to send welcome mail.
            BackgroundJob.Enqueue(() => SendWelcomeMail());

            return Ok();
        }

        [HttpPost("addtocart")]
        public IActionResult AddToCart()
        {
            // add item to user's cart

            // create scheduled job to send reminder mail if user has not completed order.
            BackgroundJob.Schedule(() => SendReminder(), TimeSpan.FromMinutes(5));

            return Ok();
        }

        [HttpGet("addrecurringjob")]
        public IActionResult AddRecurringJob()
        {
            RecurringJob.AddOrUpdate("Pending Deliveries Job", () => CheckPendingDeliveries(), Cron.Hourly);

            return Ok();
        }

        public static void SendWelcomeMail()
        {
            Console.WriteLine("Welcome mail has been sent to user");
        }

        public static void SendReminder()
        {
            bool completed = new Random().Next() % 2 == 0;

            if (completed)
            {
                Console.WriteLine("The user has already completed the order for cart item xxxx");
            }
            else
            {
                Console.WriteLine("A reminder has been sent to user for cart item xxxx");
            }
        }

        public static void CheckPendingDeliveries()
        {
            int number = new Random().Next(1, 10);

            Console.WriteLine($"There are {number} pending deliveries");
        }
    }
}

The BackgroundJob class provides static methods for creating fire-and-forget jobs, delayed jobs and continuation jobs.
The Enqueue method is used to create fire-and-forget jobs, and takes in the method call expression as a parameter. The Schedule method is used to create delayed jobs, and takes in the method call expression and a timespan indicating the delay.

The RecurringJob class provides static methods for creating and managing recurring jobs.
The AddOrUpdate method adds a new recurring job or updates an existing one. It takes in the job ID, the method call expression and the Cron expression for the interval.

When we run the application, we see the Swagger index page and our three endpoints. Calling the endpoints will create the different jobs we have set up.

When we navigate to the Hangfire dashboard, we can see information about the jobs.

As we can see, the Hangfire dashboard displays information about running and scheduled jobs, and also their success or failed status.

If we look at the HangfireDB we created earlier, we can see that a bunch of tables have been generated.

Summary

In this article we looked at how to use Hangfire to schedule background jobs in ASP.NET according to our requirements. In a follow up article, I will talk about using Hangfire with a Redis storage.
To learn more about Hangfire, you can visit the official website.

Introduction to Clean Architecture with .NET

Chinonso Ikewelugo — Sat, 12 Nov 2022 12:31:57 +0000

In this article, we're going to talk about Clean Architecture and its many benefits.

Prerequisites

Knowledge of C# and .NET
Basic understanding of the Dependency Inversion Principle

Let's get right to it.

Introduction

The smallest possible number of projects for an application architecture in .NET is one. Here, the entirety of the application, the business, presentation, and data access logic is contained in a single project, compiled to a single assembly, and deployed as a single unit. This type of all-in-one architecture might serve small applications well, but as applications get bigger this becomes unsustainable.

Folders relating to each aspect of the project can keep growing and get scattered across with no apparent cohesiveness between related folders, for example, user interface logic can reside in different folders (models, views, controllers), same with business and data access logic. Along with this, there is no clear indication of which classes in which folders should depend on which others. This lack of organization at the project level frequently leads to what is called spaghetti code.

Layers to the Rescue

To mitigate the issues mentioned above, applications often evolve into multi-project solutions, where each project represents a particular layer of the solution. Layers represent logical separation within the application. They are a way to manage complexity by breaking an application into different parts according to its responsibilities or concerns.

The most common organization of application logic into layers is shown below.

Quick Explanation of Terms

User Interface/ Presentation

This is the entry point of the application. It is the part of the application that the client/user interracts with.

Business Logic

This part is where the main implementation of an application is carried out. This part is responsible for solving whatever problem the application has set out to solve.

Data Access Logic

This is the part of the application that provides easy and simplified access to data stored in persistent storage, eg data stored in an SQL database.

Continuation

Using this architecture, user can communicate with the UIL, which in turn communicates with the BLL, which communicates with the DAL. The UIL should not speak to the DAL directly, or implement persistence by any other means. This way, each layer has its own well-defined responsibility.

However, this traditional layering approach also has a disadvantage, because dependencies seem to flow downward; the UIL depends on the BLL, and the BLL on the DAL. The business logic layer, which usually holds the most important logic of the application, depending on the data access details poses a problem, for example, tesing the BLL can be difficult because we now require a test database. Making changes to your data access details can also result in changes to the BLL.

Enter Clean Architecture

Clean architecture puts the business logic at the center of the application. This is achieved mainly by following the Dependency Inversion Principle (DIP). If you're unfamiliar with this topic, you can check out a brief overview here.

Instead of having the application core (which contains the business logic) depend on data access and other infrastructure details, this dependency is inverted; infrastructure and implementation details depend on the application core. This is achieved by defining abstractions (interfaces) in the Application Core, which will be implemented by types defined in the Infrastructure layer. Below is a diagram depicting a common visualization of Clean Architecture.

As you can see from the figure above, dependencies in Clean Architecture flow inward, and the Application Core has no dependencies on any other layers. The entities and interfaces are at the very center. Outside this, but still in the Application Core, we have the domain services, which typically implement the interfaces defined in the inner circle.

The Infrastructure and UI layers both depend on the Application Core, but not necessarily on each other. Since the Application Core doesn’t depend on the Infrastructure, it’s very easy to write automated unit tests for this layer. Also, since the UI layer doesn't have any direct dependency on the Infrastrucure layer, it is also easy to swap out implementations, either for testing purposes or due to changing technical requirements (for example, switching the UI layer from a MVC project to a Web API).

Organizing Code in Clean Architecture

Layers in applications that follow Clean Architecture have specific, well-defined responsibilities. As such, certain types belong in each project, and developers can easily find where certain functionality is implemented.

Application Core

The Application Core contains the main business logic of the application; the entities, interfaces, and the domain services, along with few other types central to the business logic.

Application Core Types

Entities
Interfaces
Services
Data Transfer Objects
Specifications
Custom Exceptions and Handlers, etc

Infrastructure

The Infrastructure project typically includes data access implementations. In a project developed using Entity Framework, the Infrastructure layer would also contain the DbContext implementation, and any migration objects that have been created. The Infrastructure layer is also where you would find infrastructure-specific services (eg mailing services). These services would implement interfaces defined in the Application Core

Infrastructure Layer Types

EF Core DbContext
Migrations
Infrastructure-specific services

UI/Presentation

This layer is the entry point of the application. It is also in this layer that the application is configured and implementation types are provided for interfaces defined in the Application Core.

UI/Presentation Layer Types

Controllers
View
ViewModels
Custom middlewares/filters
Program.cs
Startup.cs

Conclusion

This has been a brief overview of Clean Architecture and its benefits. Microsoft has provided a sample ASP.NET Core 6.0 reference application implementing Clean Architecture. You can view it here to get a more practical understanding of this topic.

Resources

Microsoft Documentation - https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures
EShopOnWeb - https://github.com/dotnet-architecture/eShopOnWeb

API Authentication using Laravel Sanctum

Chinonso Ikewelugo — Mon, 10 Jan 2022 06:55:31 +0000

In this tutorial, we’re going look at what the Laravel Sanctum package is and what it does.
Sanctum is a Laravel package which provides a simple means for authenticating your SPAs, mobile apps, and simple token-based APIs.
Let’s get right to it.

#Step 1
We will begin by creating a new Laravel project.

laravel new lara-vue

I’m using Laragon for my local development, so I can access my project by visiting http://lara-vue.test. You can access yours according to the configurations of your local server
Next, create your database and edit the contents of the .env file in your app’s root directory.

DB_CONNECTION = mysql
DB_HOST = 127.0.0.1
DB_PORT = 3306
DB_DATABASE = YourDBName
DB_USERNAME = YourDBUsername
DB_PASSWORD = YourDBPassoword

#Step 2
We can now install Laravel Sanctum

composer require laravel/sanctum

After installation, we will publish the Sanctum configuration and migration files using the vendor:publish Artisan command.

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

This command will place the configuration file in the config directory of our project.
Next, we run the database migrations. Sanctum will create a database table in which to store API tokens.

php artisan migrate

Output

Migration table created successfully.
...
Migrating: 2019_12_14_000001_create_personal_access_tokens_table
Migrated:  2019_12_14_000001_create_personal_access_tokens_table (1,081.77ms)

You will notice that a personal_access_tokens table has been added to your database. This is where the user tokens will be stored.

Next, add Sanctum's middleware to your API middleware group in the app/Http/Kernel.php file

'api' => [
    \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
    'throttle:api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
]

#Step 3
To use tokens to authenticate users, we have to add the HasApiToken trait to the app/models/User model.

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
    ...
}

When making requests using API tokens, the token should be included in the Authorization header as a Bearer token.

#Step 4
Let us now create our authentication routes in the routes/api.php file

use App\Http\Controllers\AuthController;

Route::post('/register', [AuthController::class, 'register']);
Route::post('/login', [AuthController::class, 'login'])->name('login');

Route::middleware('auth:sanctum')->group(function () {
    Route::post('/logout', [AuthController::class, 'logout']);
});

If you noticed, we called AuthController without creating it. Let us create it using this simple command

php artisan make:controller AuthController

Now, in our AuthController,

    public function register(Request $request)
    {
        try{
            $attributes= $request->validate(
                [
                    'name'=>'required|min:3|max:30',
                    'email'=>'required|email|unique:users',
                    'password'=>'required|min:6|max:30',
                ]
            );

            $attributes['password']= bcrypt($attributes['password']);

            $user = User::create($attributes);

            $message= "Account created successfully, welcome aboard.";
            $success= true;
        } catch(Exception $e){
            $success= false;
            $message= $e->getMessage();
        }


        $response= [
            'success'=>$success,
            'message'=>$message,
        ];

        return response()->json($response);
    }

    public function login(Request $request)
    {
        $attributes= $request->validate(
            [
                'email'=>'required|email',
                'password'=>'required',
            ]
        );

        if(!auth()->attempt($attributes)){
            return response()->json(
                ['message'=>'These credentials do not match our records'], 401
            );
        }

        $user= auth()->user();
        $token= $user->createToken($user->id)->plainTextToken;

        $message= "User logged in successfully";
        $success= true;

        $response= [
            'success'=>$success,
            'message'=>$message,
            'data'=>[
                'user'=>$user,
                'token'=>$token,
            ],
        ];     

        return response()->json($response, 200);
    }


    public function logout()
    {
        Session::flush();
        $success= true;
        $message= 'User logged out successfully';

        $response= [
            'success'=>$success,
            'message'=>$message,
        ];

        return response()->json($response);
    }

Here, we set up our authentication logic. The register method creates a new user in our app, the login method authenticates users and generates an access token on succesful login, and the logout method removes the user's session.

#Step 5
All we have left to do is test our implementation. We can do this using Postman or Insomnia packages. We'll send requests to our register and login routes.

If everything works well, we will receive a JSON response similar to this:
Registration Response:

{
    "success":true,
    "message":"Account created successfully, welcome aboard."
}

{
    "success":true,
    "message":"User logged in successfully"
    "data":{
        "user": {
            "id": 1,
            "name": "Emeka Ike",
            "email": "emekaike@test.com",
            "email_verified_at": null,
            "created_at": null,
            "updated_at": null
        },
        "token": "uIuSGRGAblahGHblah..."
    }
}

Conclusion
In this tutorial, we looked at what Laravel Sanctum is and what it does. We covered how to install and setup Sanctum, and how to use it to authenticate and give access to users. This gives us the power to build powerful APIs.

You can view the source code for this tutorial here.

I hope you found this helpful, and if you have any questions, just let me know in the comments and I will clarify further.