ASP.NET Core is a versatile and robust web application framework. Middleware is one of its core characteristics, and it plays a critical role in processing requests and responses as they travel through your application. This post will explain what middleware is, how it works, and why it is necessary for developing powerful online applications in ASP.NET Core.

ASP.NET Core Middleware

In ASP.NET Core, middleware is a collection of components that are added to the application's request processing pipeline. Each middleware component is responsible for processing an incoming request or an outgoing answer. Middleware components can be added, removed, or reordered, allowing developers to tailor the request-handling pipeline to the specific demands of their application.

Middleware can handle a wide range of responsibilities, including authentication, routing, caching, logging, and more. It functions similarly to a chain of building blocks, with each block performing a specified operation on the request or response before passing it on to the next middleware in the pipeline.

The Middleware Anatomy
In ASP.NET Core, middleware components are often implemented as classes with a specified signature. They accept an HTTP context containing information about the incoming request and allow them to modify the answer. This is the fundamental structure of middleware.

public class MyMiddleware
{
    private readonly RequestDelegate _next;

    public MyMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Do something before the next middleware
        // ...

        await _next(context); // Call the next middleware in the pipeline

        // Do something after the next middleware
        // ...
    }
}

In this case, RequestDelegate represents the next middleware in the pipeline, and the InvokeAsync method provides the logic that will run before and after the next middleware.

In Use Middleware
Consider the following example, in which we wish to track the path of each incoming request.

public class LoggingMiddleware
{
    private readonly RequestDelegate _next;

    public LoggingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Log the request path
        Console.WriteLine($"Request to: {context.Request.Path}");

        await _next(context); // Call the next middleware in the pipeline
    }
}

We can add this middleware to the pipeline in the Startup.cs file.
public void Configure(IApplicationBuilder app)
{
    app.UseMiddleware<LoggingMiddleware>();

    // Other middleware and configuration...
}

Now, every incoming request's path will be logged before it proceeds through the pipeline.

Ordering Middleware
The order in which middleware components are added to the pipeline matters. Middleware is executed in the order it's added, from top to bottom. For example, if you want to perform authentication before routing, you should add authentication middleware before routing middleware.

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication(); // Add authentication middleware
    app.UseRouting(); // Add routing middleware

    // Other middleware and configuration...
}

Middleware is a fundamental concept in ASP.NET Core, allowing you to modularize and customize request and response processing in your web applications. By understanding how middleware works and how to leverage it effectively, you can build robust and flexible web applications that meet your specific requirements. Whether you're handling authentication, logging, or any other aspect of request processing, middleware is a powerful tool in your ASP.NET Core toolbox.

Asynchronous programming has become an essential aspect of modern software development, and.NET Core (now known as.NET 5,.NET 6,.NET 7, and later.NET 8) provides strong capabilities to make asynchronous processes easier. When working with tasks, you have two fundamental methods at your disposal: WaitAll and WhenAll. These methods enable you to efficiently manage and coordinate several asynchronous operations. In this blog post, we will look at WaitAll and WhenAll in.NET Core and learn about their differences and applications.

The Fundamentals of.NET Core Asynchronous Programming
Before diving into WaitAll and WhenAll, it's critical to understand the principles of.NET Core asynchronous programming. Asynchronous operations allow your application to run numerous tasks at the same time without interrupting the main thread, which improves responsiveness and speed. You deal with tasks in.NET Core, which represent units of work that can run concurrently.

public async Task DoSomeWorkAsync()
{
    // Perform asynchronous operations
    await Task.Delay(1000); // Simulate work
    // Continue with other operations
}

WaitAll - Waiting for All Tasks to Complete
Task.WaitAll is a synchronous method that blocks the current thread until all the provided tasks have completed. It ensures that all tasks finish their execution before allowing the program to proceed further. This is particularly useful when you need to perform actions only when all tasks are done.

async Task PerformMultipleOperationFromWaitllAsync()
{
    WaitAllSample waitAllSample = new WaitAllSample();
    Task task1 = waitAllSample.DoSomeWorkAsync();
    Task task2 = waitAllSample.DoSomeOtherWorkAsync();
    Task.WaitAll(task1, task2);
    Console.WriteLine("All tasks in WaitAll are complete!");

}

Using Task, on the other hand.WaitAll can cause thread blocking and may not be appropriate in all cases, particularly in UI applications where blocking the main thread can result in a frozen interface.

WhenAll - Concurrently Awaiting All Tasks

WhenAll is an asynchronous method that returns a new task that finishes when all of the specified tasks have completed. Rather of blocking the thread, it lets the computer to continue processing other activities or managing user input, which is essential for responsive apps.

async Task PerformMultipleOperationFromWhenAllAsync()
{
    WhenAllExample whenallexample = new WhenAllExample();
    Task task3 = whenallexample.DoSomethingAsync();
    Task task4 = whenallexample.DoSomethingElseAsync();
    await Task.WhenAll(task3, task4);
    Console.WriteLine("All tasks in WhenAll are complete!");
}

Task.WhenAll is better suited for cases in which numerous asynchronous operations must be performed concurrently without blocking the main thread. It is essential for developing responsive and efficient applications.

Important distinctions between WaitAll and WhenAll
Task.WaitAll is a synchronous method that causes the current thread to be blocked, whereas Task.Because WhenAll is asynchronous, additional processes can execute concurrently.
When you wish to wait for all tasks to finish before proceeding, Task.WaitAll is useful, whereas Task.WhenAll allows you to continue performing other tasks while waiting for tasks to complete.
Task.WaitAll may cause thread-blocking, rendering it inappropriate for UI applications, whereas Task.WhenAll is better suited for responsive interfaces.
Task.WaitAll is older and is frequently used in legacy programs, whereas Task.WhenAll is the ideal and modern method of managing many tasks in.NET Core.

Conclusion
Asynchronous programming is a useful technique in.NET Core for improving application responsiveness and performance. Task.Task and WaitAll.WhenAll methods are critical for managing and coordinating several asynchronous tasks. You may make informed selections when selecting the correct strategy for your specific circumstance if you understand their distinctions and use cases. .NET Core delivers the tools you need to build efficient and responsive apps, whether you need to wait for all actions to complete synchronously or proceed with other processes simultaneously.

ASP.NET Core is a versatile and robust web application framework. It offers a comprehensive collection of capabilities for developing strong and scalable applications, with Action Filters being one of the essential aspects that increase its functionality. Action filters allow you to execute code before or after an action method is executed, allowing you to add cross-cutting concerns to your application. In this post, we will look at action filters in ASP.NET Core, learn about their different types, and how to develop custom filters to improve the functionality of your web application.

What exactly are Action Filters?
In ASP.NET Core, action filters are properties that can be applied to controller action methods to do pre- or post-processing. They enable you to add functionality that is executed before or after action methods are invoked. Cross-cutting concerns like as logging, authentication, caching, and others can be implemented via action filters.

There are five types of action filters in ASP.NET Core.

• Authorization Filter
• Resource Filter
• Action Filter
• Result Filter
• Exception Filter

Filter for Authorization
An authorization filter is essential for enforcing authentication and authorisation rules in your web application. Authorization filters are commonly used to guarantee that only authenticated and authorized users have access to certain areas of your application. These filters are run before the action method, allowing you to validate the user's credentials and permissions before granting or denying access. They are an important part of implementing security and access control in ASP.NET Core applications.

Example
Assume you have a controller with an action method to which you wish to limit access based on user roles. In this scenario, we'll use an Authorization Filter to determine whether or not the user has a specified role before granting access to the action method.

First, define a custom Authorization Filter.
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.AspNetCore.Http;
using System;

public class CustomAuthorizationFilter : Attribute, IAuthorizationFilter
{
public void OnAuthorization(AuthorizationFilterContext context)
{
    // Check if the user is in the "Admin" role
    if (!context.HttpContext.User.IsInRole("Admin"))
    {
        // If not, deny access and return a forbidden status
        context.Result = new StatusCodeResult(StatusCodes.Status403Forbidden);
    }
}
}

Next, apply the CustomAuthorizationFilter to your action method.
[CustomAuthorizationFilter] // Apply the custom authorization filter
public IActionResult AdminOnlyAction()
{
// This action is only accessible to users in the "Admin" role
return View();
}

In this example, the CustomAuthorizationFilter is applied to the AdminOnlyAction method. When a user tries to access this action, the filter checks if they are in the "Admin" role using the IsInRole method. If the user is not in the "Admin" role, the filter sets the HTTP response status code to 403 Forbidden, denying access to the action.

Resource Filter
Resource Filters in ASP.NET Core are a type of action filter that allows you to perform actions that affect the entire HTTP request and response, such as modifying response headers or handling global exceptions. These filters execute before any other filter type (Authorization, Action, Result, and Exception filters) have access to the HTTP context and can influence the entire request processing pipeline.

• Global Exception Handling: Resource filters can be used to handle exceptions that occur during the request processing pipeline. By implementing a resource filter for exception handling, you can catch and handle exceptions globally, providing a consistent way to log errors, display custom error pages, or perform other actions.
• Response Modification: You can modify the response object, such as adding custom response headers, changing the status code, or altering the response content, using resource filters.
• Request Preprocessing: Resource filters can perform actions at the beginning of the request pipeline, such as setting request-specific variables or performing other pre-processing tasks.
• Global Logging: You can use resource filters for global logging to log information about incoming requests, response times, or other metrics that apply to the entire application.

Example
Let's create a simple resource filter that adds a custom response header to every response in your ASP.NET Core application. In this example, we'll add a "X-Custom-Header" to the response.

Create a custom resource filter.
using Microsoft.AspNetCore.Mvc.Filters;

public class AddCustomHeaderResourceFilter : IResourceFilter
{
public void OnResourceExecuting(ResourceExecutingContext context)
{
    // Code to execute before the action
    context.HttpContext.Response.Headers.Add("X-Custom-Header", "MyCustomValue");
}

public void OnResourceExecuted(ResourceExecutedContext context)
{
    // Code to execute after the action
}
}

You can do this in the ConfigureServices method.
services.AddMvc(options =>
{
options.Filters.Add<AddCustomHeaderResourceFilter>();
});

Now, this resource filter will be executed for every request in your ASP.NET Core application, and it will add the "X-Custom-Header" to the response headers.

Resource filters are a powerful way to perform global actions that apply to all requests and responses in your application, making them a valuable tool for tasks like global exception handling, response modification, and request preprocessing.

Action Filter
Action Filters in ASP.NET Core are attributes that allow you to add logic that runs before and after the execution of individual action methods in your controllers. These filters are used to perform tasks such as logging, input validation, modifying the action result, and more.

Example
Let's create a simple Action Filter to log the start and end of an action method.

Create a custom Action Filter.
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Logging;

public class LogActionFilter : IActionFilter
{
private readonly ILogger<LogActionFilter> _logger;

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

public void OnActionExecuting(ActionExecutingContext context)
{
    // This method runs before the action method
    _logger.LogInformation($"Action '{context.ActionDescriptor.DisplayName}' is starting.");
}

public void OnActionExecuted(ActionExecutedContext context)
{
    // This method runs after the action method
    _logger.LogInformation($"Action '{context.ActionDescriptor.DisplayName}' has completed.");
}
}

You can do this in the ConfigureServices method.
services.AddMvc(options =>
{
options.Filters.Add<LogActionFilter>();
});

Apply the Action Filter to a controller action method.
[ServiceFilter(typeof(LogActionFilter))] // Apply the filter to this action method
public IActionResult MyAction()
{
// Your action method logic
}

Now, whenever you call the MyAction method, the LogActionFilter will log the start and end of the action, providing you with a simple way to monitor the execution of your action methods.

Result Filter
Result Filters in ASP.NET Core are a type of action filter that executes code after an action method has been executed but before the result is processed and sent to the client. These filters are useful for modifying the response or result, adding custom headers, or performing actions related to the response before it is returned to the client.

Example
Let's create a simple Result Filter to add a custom header to the response.

Create a custom Result Filter.
using Microsoft.AspNetCore.Mvc.Filters;

public class AddCustomHeaderResultFilter : IResultFilter
{
public void OnResultExecuting(ResultExecutingContext context)
{
    // This method runs before the result is executed
    context.HttpContext.Response.Headers.Add("X-Custom-Header", "MyCustomValue");
}

public void OnResultExecuted(ResultExecutedContext context)
{
    // This method runs after the result is executed
}
}

You can do this in the ConfigureServices method.
services.AddMvc(options =>
{
options.Filters.Add<AddCustomHeaderResultFilter>();
});

Apply the Result Filter to a controller action method.
[ServiceFilter(typeof(AddCustomHeaderResultFilter))] // Apply the filter to this action method
public IActionResult MyAction()
{
// Your action method logic
}

When you call the MyAction method, the AddCustomHeaderResultFilter will add the "X-Custom-Header" to the response headers before it's sent to the client. This can be useful for scenarios where you want to add custom response headers, set response content types, or perform other response-related actions.

Exception Filter
Exception Filters in ASP.NET Core are a type of action filter that are specifically designed to handle exceptions that occur during the execution of an action method. These filters allow you to define custom logic to gracefully handle and respond to exceptions, providing a way to centralize error handling and improve the user experience.

How Exception Filters Work?
Exception filters are executed when an unhandled exception is thrown during the execution of an action method. They intercept the exception before it propagates up the call stack and provide an opportunity to perform custom error handling.
Use Cases for Exception Filters

Custom Error Pages: Exception filters can redirect the user to custom error pages, displaying user-friendly error messages instead of the default error page.
Logging and Reporting: You can use exception filters to log exceptions, making it easier to identify and fix issues. You can also report exceptions to external systems for further analysis.
Graceful Degradation: In cases where an exception occurs but the application can still function to some extent, an exception filter can handle the error and return a partial or degraded response instead of a complete failure.

Example
Let's create a simple Exception Filter to log and handle exceptions.

Create a custom Exception Filter.
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Logging;

public class CustomExceptionFilter : IExceptionFilter
{
private readonly ILogger<CustomExceptionFilter> _logger;

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

public void OnException(ExceptionContext context)
{
    // Log the exception
    _logger.LogError($"An exception occurred: {context.Exception.Message}");

    // Handle the exception
    context.Result = new ViewResult { ViewName = "Error" };
    context.ExceptionHandled = true;
}
}

You can do this in the ConfigureServices method.
services.AddMvc(options =>
{
options.Filters.Add<CustomExceptionFilter>();
});

Apply the Exception Filter to a controller action method.
[ServiceFilter(typeof(CustomExceptionFilter))] // Apply the filter to this action method
public IActionResult MyAction()
{
// Your action method logic
}

If an unhandled exception occurs in the MyAction method, the CustomExceptionFilter will log the error and redirect the user to a custom error page.

Real-World Use Cases
Action filters are incredibly versatile and can be applied to a wide range of scenarios. Here are some real-world use cases for action filters in ASP.NET Core.

• Logging: You can create an action filter that logs information about the execution of action methods, helping with debugging and monitoring.
• Validation: Implement input validation checks before an action method is executed to ensure that the input data is valid.
• Caching: Use action filters to cache the results of action methods to improve performance and reduce database or API calls.
• Security: Implement security checks and authorization logic using action filters to restrict access to certain action methods based on user roles and permissions.
• Exception Handling: Create custom exception filters to handle and log exceptions in a consistent and user-friendly manner.

Optimization of performance is an important part of software development. As developers, we frequently attempt to write code that is efficient and speedy. However, precisely assessing code performance can be difficult. This is where BenchmarkDotNet, a powerful.NET benchmarking library, comes in. In this post, we'll look at the capabilities of BenchmarkDotNet and show you how to use it to test your.NET programs.

What exactly is BenchmarkDotNet?
BenchmarkDotNet is an open-source.NET benchmarking library. It enables developers to create, execute, and evaluate benchmarks in order to assess the performance of their programs. BenchmarkDotNet is a vital tool for optimizing.NET applications since it provides precise measurements, many run modes, and statistical analysis.

Starting Over
Before we begin benchmarking, please confirm that BenchmarkDotNet is installed in your project. You may install it with the following command in the NuGet Package Manager Console:
dotnet add package BenchmarkDotNet

Creating Your First BenchmarkLet's create a simple benchmark to compare the performance of two different implementations of a function. Consider the following example where we want to find the factorial of a number. Now you create the ConsoleApp.

Create a Class name FactorialCalculator

public class FactorialCalculator
{
    public int CalculateRecursive(int n)
    {
        if (n == 0 || n == 1)
        {
            return 1;
        }
        return n * CalculateRecursive(n - 1);
    }

    public int CalculateIterative(int n)
    {
        int result = 1;
        for (int i = 1; i <= n; i++)
        {
            result *= i;
        }
        return result;
    }
}

Let's use BenchmarkDotNet to create benchmarks for these methods and measure their performance.
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using ConsoleApp2;

class Program
{
static void Main(string[] args)
{
    var summary = BenchmarkRunner.Run<FactorialBenchmarks>();
}
}

public class FactorialBenchmarks
{
private readonly FactorialCalculator _calculator = new FactorialCalculator();

[Benchmark]
public void RecursiveBenchmark()
{
    _calculator.CalculateRecursive(10);
}

[Benchmark]
public void IterativeBenchmark()
{
    _calculator.CalculateIterative(10);
}
}

In this example, we've created two benchmarks, RecursiveBenchmark and IterativeBenchmark, using the Benchmark attribute. The BenchmarkRunner.Run method triggers the benchmarks and generates a detailed report.
Running Benchmarks

Build in RELEASE Mode

• Open a terminal or command prompt.
• Navigate to the project directory using the cd command.

Run the following command to build the project in RELEASE mode:

Run Benchmarks
After building the project in RELEASE mode, you can run your benchmarks using the dotnet run command.
When building your project, it is crucial to do so in RELEASE mode in order to guarantee that the compiler applies optimizations. This will lead to more precise benchmark results. By following this suggestion, you can avoid receiving warning messages and anticipate dependable performance measurements for your benchmarks.
When you have run it then you see

It may take some time for the results to display after running the application.

It may take some time for the results to display after running the application.

• WorkloadPilot is the code you want to measure.
• OverheadWarmup and OverheadActual account for the time and resources consumed by BenchmarkDotNet itself.
• WorkloadWarmup measures the time it takes for your code to stabilize during the warm-up phase.
• WorkloadActual measures the actual performance of your code once it has reached a stable state.

Result Summary Section

The two methods we're evaluating are listed in the overview section, along with their performance metrics. The mean measure, which is the average time it takes to run each procedure, is the most essential metric.

Conclusion
BenchmarkDotNet streamlines the process of measuring performance in.NET applications. It enables developers to find bottlenecks and improve their code effectively by delivering reliable data and statistical analysis. Consider incorporating BenchmarkDotNet into your workflow as you continue to develop high-performance applications to guarantee your code runs as efficiently as possible.

A circuit breaker is a software development design pattern intended to improve the resilience and fault tolerance of programs that connect with external services or resources. It takes its name from its electrical counterpart, which is intended to safeguard an electrical circuit from harm caused by high current. A circuit breaker in software performs a similar function by preventing the application from continually attempting to call a malfunctioning service or resource, which might lead to performance deterioration and other issues.

Circuit Breaker Diagram
Here's a breakdown of the circuit breaker pattern.

1. Normal Operation (Closed State)

    When the circuit breaker is closed, requests can travel through normally.
    It tracks the success and failure of these queries during this condition.
    When a particular number of failures are reached, the circuit breaker switches to the open position.

2. Unavailable State (Service)

    When the circuit breaker is open, it prevents requests from reaching the failing service or resource.
    This condition is activated when a preset number of failures is exceeded.
    No requests are sent to the service/resource while it is open, which might minimize the stress on the resource.
    The circuit breaker verifies if the service/resource has recovered on a regular basis by allowing a restricted number of test requests to get through.

3. Half-Open State (Service Availability Testing)

    After a predetermined period of time, the circuit breaker switches to the half-open position.
    In this condition, only a limited number of test requests can be sent to the service/resource to see if it has recovered.
    If these test requests are successful, the circuit breaker returns to the closed position.
    If the test requests continue to fail, the circuit breaker returns to the open position, protecting the system from additional failures.

Important Concepts

• Circuit breakers have thresholds that determine when they switch between states. The number of successive failures, the failure rate, or a combination of factors could be used to set these criteria.
• Timers: Timers regulate how long the circuit breaker stays in each state. For example, it may remain in the open state for a predetermined period of time before shifting to the half-open state.
• Monitoring and request tracking are required to determine the health of the service or resource and to determine when to open or close the circuit.
• Fallback Mechanism: While in the open state, apps can design fallback mechanisms to provide alternative functionality or smooth service degradation.
• Automated Recovery: When the service/resource appears to have recovered, circuit breakers automatically return to the closed state, decreasing the impact on the system.

By isolating problematic services or resources, the circuit breaker design helps to prevent cascading failures in distributed systems, enhances system stability, and provides a level of fault tolerance. It is a basic idea in the development of strong and resilient software systems.

Circuit Breaker Pattern in .Net Core
Let's implement the same in .Net Core using two different approaches.

• Approach 1 - Without using any specific Nuget package
• Approach 2 - Using Polly Nuget package

Common steps for both approaches( will also upload the solution with this article). I am using Visual Studio for mac but you can use Visual Studio code as well.

Create a new .NET Core API Project
Add a new interface for service and the concrete service class with HttpClient as a dependency
In the concrete service, add code to make an HttpRequest to a random api and get request. I am using an open source webapi for getting random jokes
Add a controller and call the above created service in it

Joke Interface
namespace CircuitBreaker
{
    public interface IJokeService
    {
        public Task<string> GetRandomJokes();
    }
}

Joke Service
namespace CircuitBreaker
{
    public class JokeService : IJokeService
    {
        private readonly HttpClient _httpClient;

        public JokeService(HttpClient httpClient)
        {
            _httpClient = httpClient;
        }

        public async Task<string> GetRandomJokes()
        {
            try
            {
                var request = new HttpRequestMessage
                {
                    Method = HttpMethod.Get,
                    RequestUri = new Uri("https://official-joke-api.appspot.com/random_joke")
                };
                var response = await _httpClient.SendAsync(request);
                response.EnsureSuccessStatusCode();

                var responseBody = await response.Content.ReadAsStringAsync();
                return responseBody;
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }
    }
}

Joke Controller
using Microsoft.AspNetCore.Mvc;

namespace CircuitBreaker.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class JokeController : ControllerBase
    {
        public readonly IJokeService _jokeService;

        public JokeController(IJokeService jokeService)
        {
            _jokeService = jokeService;
        }

        [HttpGet(Name ="GetRandomeJokes")]
        public async Task<IActionResult> Get()
        {
            try
            {
                var response = await _jokeService.GetRandomJokes();
                return Ok(response);
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }
    }
}

Program.cs/StartUp.cs
public static void ConfigureService(IServiceCollection services)
{
    services.AddHttpClient<IJokeService, JokeService>();
}

Sample output
{"type":"general","setup":"What's brown and sticky?","punchline":"A stick.","id":271}

Now, the circuit breaker strategy usually allows an n number of failed tries before not-allowing any futher requests and breaking the circuite for some time. These n tries are with state, let me explain in more clarity.

Let's suppose the n count is 3 and 3 three different users tries to access the api one after the other(irrespective of the time difference between these requests) and if all three of these fails, then the 4th atempt should not even go through. The code should not further try to hit the other api untill a specifc time internal. Uptill this time interval, all requests attempts will just by-pass the api call and provide a message to end-user to try after some time. This can go in a loop if the other api issue is not resolved. This helps in making sure that the other service that we are calling is not overwhelmed with failing requests.

Let's try to implement this in Approach 1.

Create some static variables. We are creating them static as we want to persist the value of them between different calls. Please read comments for more understanding of each of it's use
//count of failed attempts that have been made
private static int attemptCount = 0;

//count of failed attempts allowed, post which the circiut will break
private static int maxAttemptCount = 3;

//flag to represent if the circuit is open or close
private static bool isCircuitOpen = false;

//field to keep a track of the utc time when the circuit was opened/broken
private static DateTime circuitOpenStartTime = DateTime.MinValue;

//the timestamp (in millisecond) for which the circuit should remain open and api call attempts should not be made
private static int circuitBreakerTimeSpanMilliseconds = 120000;

//method to start the circuit breaker
//if sets the isCircuitOpen to true and sets the time when the circuit was broken in utc
private void RecordCircuitBreakerStart()
{
    circuitOpenStartTime = DateTime.UtcNow;
    isCircuitOpen = true;
}

//method to end the circuit breaker
private void RecordCircuitBreakerEnd()
{
    circuitOpenStartTime = DateTime.MinValue;
    isCircuitOpen = false;
    attemptCount = 0;
}

//check if currently the circuit is broken or not
private void CheckIfCircuitBreakerTimeStampIsComplete()
{
    if(isCircuitOpen == true && circuitOpenStartTime.AddMilliseconds(circuitBreakerTimeSpanMilliseconds) < DateTime.UtcNow)
    {
        RecordCircuitBreakerEnd();
     }
}

Now, let's call the above method in our controller method
public async Task<string> GetRandomJokes()
{
    try
    {
        //check if the circuit was earlier open can can be closed now
        CheckIfCircuitBreakerTimeStampIsComplete();
        if (isCircuitOpen == false)
        {
            #region MakeAPICall
            var request = new HttpRequestMessage
            {
                Method = HttpMethod.Get,
                RequestUri = new Uri("https://official-joke-api.appspot.com/random_joke")
            };
            var response = await _httpClient.SendAsync(request);
            response.EnsureSuccessStatusCode();

            var responseBody = await response.Content.ReadAsStringAsync();
            return responseBody;

            #endregion
        }
        return "Service is not available. Please try after some time";
    }
    catch (Exception ex)
    {

        //in case of exception, if the max attempt of failure is not yet reached, then increase the counter
        if(isCircuitOpen == false && attemptCount < maxAttemptCount)
        {
            attemptCount++;
        }
        //if the count of max attempt if reached, then open the circuits and retuen message that the service is not available
        if(attemptCount == maxAttemptCount)
        {
            if (isCircuitOpen == false)
            {
                RecordCircuitBreakerStart();
            }
            return "Service is not reachable. Please try after some time";
        }
        return ex.Message;
    }
}

I agree with what you all must be thinking, the above approach is indeed messy and prone to more errors as we are managing multiple things at the same time. In order to make this code more readable and less error prone, we move to Approach 2

Approach 2 - In this we use an existing Nuget package, called Polly to achieve the same.

In the above code, add the nuget package Polly as in the screenshot below:

Add another nuget package - Microsoft.Extensions.Http.Polly to the solution
These packages enable us to define different policies to come into effect in case of an error. One of such policy is CircuitBreaker. Other policies to look at are RetryPolicy and WaitAndRetryPolicy.

For this, we will be adding another interface method and another service method called GetRandomJokesV2().

namespace CircuitBreaker
{
    public interface IJokeService
    {
        public Task<string> GetRandomJokes();
        public Task<string> GetRandomJokesV2();
    }
}

public async Task<string> GetRandomJokesV2()
{

    try
    {
            var request = new HttpRequestMessage
            {
                Method = HttpMethod.Get,
                RequestUri = new Uri("https://official-joke-api.appspot.com/random_joke")
            };
            var response = await _httpClient.SendAsync(request);
            response.EnsureSuccessStatusCode();

            var responseBody = await response.Content.ReadAsStringAsync();
            return responseBody;
    }

    catch (BrokenCircuitException ex)
    {

        return $"Request failed due to opened circuit: {ex.Message}";
    }
    catch (HttpRequestException httpEx)
    {
        return $"Request failed. StatusCode={httpEx.StatusCode} Message={httpEx.Message}";
    }
}

We then updated the ConfigureService method in Program.cs to add this policy. See code below:

public static void ConfigureService(IServiceCollection services)
{
    services.AddHttpClient<IJokeService, JokeService>(client =>
    {
        client.BaseAddress = new Uri("https://official-joke-api.appspot.com/random_joke");
    }).AddTransientHttpErrorPolicy(policy => policy.CircuitBreakerAsync(3, TimeSpan.FromMilliseconds(120000)));
}

In the above code, we are telling the middleware that in case this api call fails after 3 attempts, then by-pass all future api calls for 120000 miliseconds(2 mins). Post that there will be attempts to hit the api.

The way we call it in the Controller or servide does not change much
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;

// For more information on enabling MVC for empty projects, visit https://go.microsoft.com/fwlink/?LinkID=397860

namespace CircuitBreaker.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class JokeV2Controller : ControllerBase
    {
        public readonly IJokeService _jokeService;

        public JokeV2Controller(IJokeService jokeService)
        {
            _jokeService = jokeService;
        }

        [HttpGet(Name = "GetRandomeJokesV2")]
        public async Task<IActionResult> Get()
        {
            try
            {
                var response = await _jokeService.GetRandomJokesV2();
                return Ok(response);
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }
    }
}

We can clearly see that the Approach 2 is a more advisable and enterprise approach which makes our code more readable and less prone to errors. We can also make all the policies inside another folders as classes and inject them wherever required. This will make our code more abstract.

Please let me know your thoughts on this. I am also attaching my solutions in this post.

Middleware is the unsung hero of ASP.NET Core apps. It is critical in processing HTTP requests and responses, allowing developers to shape the flow of data in a flexible and orderly manner. In this post, we will take a tour through the diverse terrain of designing middleware in.NET Core, demonstrating real-time examples for a better understanding.

The Middleware Landscape
Middleware in ASP.NET Core serves as a link between the web server and your application. It has the ability to intercept, modify, or even short-circuit the request-response flow. Understanding the various methods for creating middleware is vital for developing powerful web applications.

1. Inline Middleware
The simplest way to create middleware is by defining it inline within the Configure method of your Startup class. Let's consider an example where we want to log incoming requests:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.Use(async (context, next) =>
    {
        // Log the incoming request
        LogRequest(context.Request);
        await next.Invoke();
        // Log the response
        LogResponse(context.Response);
    });
    // Other middleware and app configuration
}

This inline middleware logs both the request and response details for every incoming request.

2. Class-based Middleware
For more organized and reusable middleware, you can create custom middleware classes. Here's an example of a custom middleware class that performs authentication:

public class AuthenticationMiddleware
{
    private readonly RequestDelegate _next;
    public AuthenticationMiddleware(RequestDelegate next)
    {
        _next = next;
    }
    public async Task InvokeAsync(HttpContext context)
    {
        // Perform authentication logic
        if (!context.User.Identity.IsAuthenticated)
        {
            context.Response.StatusCode = 401;
            return;
        }
        await _next(context);
    }
}

In the Startup class, register and use this middleware:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseMiddleware<AuthenticationMiddleware>();
    // Other middleware and app configuration
}

3. Middleware Extension Methods
To keep your Startup class clean, you can create extension methods for middleware. Continuing with the authentication example, here's how you can create an extension method:
public static class AuthenticationMiddlewareExtensions
{
    public static IApplicationBuilder UseAuthenticationMiddleware(this IApplicationBuilder app)
    {
        return app.UseMiddleware<AuthenticationMiddleware>();
    }
}

Now, in your Startup class, using this extension method is as simple as:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseAuthenticationMiddleware();
    // Other middleware and app configuration
}

4. Middleware Pipeline Ordering
Order matters in middleware. The sequence in which you add middleware components to the pipeline affects their execution. For instance, if you have middleware that handles error responses, it should be placed after other middleware to catch exceptions.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseExceptionHandler("/Home/Error");  // Error handling middleware
    // Other middleware and app configuration
}

Summary
Middleware is a fundamental part of building robust ASP.NET Core applications. Knowing the various ways to create middleware, from inline methods to class-based and extension methods, empowers you to structure your application's request-response pipeline effectively. By understanding the order of execution in the middleware pipeline, you can ensure that each component plays its role at the right moment. As you continue your journey in ASP.NET Core development, mastering middleware creation will be a valuable skill in your toolkit, enabling you to craft efficient and resilient web applications.

Many applications demand the ability to generate PDF documents programmatically. GrapeCity's GcPdf is a comprehensive library in the.NET ecosystem that allows developers to easily generate, change, and manipulate PDF documents. This blog post will show you how to utilize GcPdf to generate PDF documents programmatically in.NET C#, with actual examples to back it up.

What exactly is GcPdf?
GcPdf is a.NET package that offers extensive PDF document production and manipulation features. It has a variety of features, including:

• Creating PDF documents from the ground up.
• Text, photos, and shapes can be added to PDF pages.
• Changing fonts and styles.
• Making tables and graphs.
• Inserting links and bookmarks.
• Exporting PDFs to various formats.
• Password protection and encryption are being added as security measures.

Let's get started with GcPdf by creating a simple PDF document.

How to Begin with GcPdf?
Make sure you have Visual Studio or your favourite C# development environment installed before we begin. In addition, you must include the GrapeCity Documents for PDF NuGet package (GcPdf) in your project.

Making a Basic PDF Document
In this example, we'll make a simple PDF file with text and a rectangle shape.

using System;
using GrapeCity.Documents.Pdf;
using GrapeCity.Documents.Text;

class Program
{
    static void Main(string[] args)
    {
        // Create a new PDF document
        var doc = new GcPdfDocument();

        // Add a page to the document
        var page = doc.NewPage();

        // Create a graphics object for drawing on the page
        var g = page.Graphics;

        // Add content to the page
        var text = "Hello, World!";
        var font = StandardFonts.Helvetica;
        var fontSize = 24;
        var textFormat = new TextFormat()
        {
            Font = font,
            FontSize = fontSize,
        };

        g.DrawString(text, textFormat, new PointF(100, 100));

        // Create a rectangle
        var rect = new RectangleF(100, 200, 200, 150);
        g.DrawRectangle(rect, Color.Red);

        // Specify the file path where you want to save the PDF
        var filePath = "example.pdf";

        // Save the document to a PDF file
        doc.Save(filePath);

        Console.WriteLine($"PDF created at {filePath}");
    }
}

Explanation of the code

• To represent the PDF document, we construct a new GcPdfDocument object.
• Using doc, add a page to the document.NewPage().
• Make a graphics object (g) to doodle on the page.
• Using g, add text and a rectangle to the page.DrawString() and g.DrawRectangle() are two functions.
• Enter the location to the file where you wish to save the PDF.
• doc Save the document as a PDF file.Save().

After running this code, a PDF file named "example.pdf" will be created in your project directory.

GcPdf Advanced Features
GcPdf has a wide range of tools for creating advanced PDF documents. Here are a few advanced features to look into:

Including Images
Using the g.DrawImage() method, you can add images to your PDF document. This enables you to insert logos, images, or photographs in your documents.

var image = Image.FromFile("logo.png");
g.DrawImage(image, new RectangleF(50, 50, 100, 100));

Making Tables
Tables are widely used to present tabular data in PDF documents. GcPdf includes a Table class that may be used to create tables with a variety of formatting choices.

var table = new Table();
table.DataSource = GetTableData(); // Replace with your data source
page.Elements.Add(table);

Adding Hyperlinks
You can include hyperlinks in your PDFs using the g.DrawString() method with a link destination.
var hyperlinkText = "Visit our website";
var linkDestination = new LinkDestinationURI("https://example.com");
g.DrawString(hyperlinkText, textFormat, new PointF(100, 300), linkDestination);

PDF Security
GcPdf allows you to secure your PDFs by adding passwords or encrypting them. You can set document permissions and control who can view or edit the document.
var options = new PdfSaveOptions
{
    Security = new PdfSecuritySettings
    {
        OwnerPassword = "owner_password",
        UserPassword = "user_password",
        Permissions = PdfPermissions.Print | PdfPermissions.Copy,
    },
};
doc.Save("secure.pdf", options);

Creating customized PDFs for various applications in .NET C# by using GcPdf programmatically is a potent and versatile method. GcPdf offers all the necessary features and flexibility to generate reports, invoices, or other types of documents quickly and efficiently. To enhance your PDF generation capabilities with more in-depth information and examples, please refer to the GcPdf documentation. We wish you happy coding!

Using tools like Swagger/OpenAPI or NSwag to create thorough API documentation for an ASP.NET Core Web API is a critical step in ensuring that your API is well-documented and easy for other developers to understand and utilize. I'll show you how to build API documentation in an ASP.NET Core Web API project using Swagger/OpenAPI in the steps below.

Step 1: Begin by creating an ASP.NET Core Web API Project.
If you do not already have an ASP.NET Core Web API project, you can build one by following the instructions below.

    Start Visual Studio or your favorite code editor.
    Make a new project and select "ASP.NET Core Web Application."
    Choose the "API" template and press "Create."

Step 2: Set up Swashbuckle.AspNetCore
Swashbuckle.AspNetCore is a library that makes integrating Swagger/OpenAPI into your ASP.NET Core Web API project easier. It may be installed using NuGet Package Manager or the.NET CLI.

dotnet add package Swashbuckle.AspNetCore

Step 3. Configure Swagger/OpenAPI
In your Startup.cs file, configure Swagger/OpenAPI in the ConfigureServices and Configure methods.
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using Swashbuckle.AspNetCore.SwaggerUI;

Author: Sardar Mudassar Ali Khan
public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "Auth API",
            Version = "v1",
            Description = "Description of your API",
        });
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });

}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{

    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Auth API");
        c.RoutePrefix = "api-docs"; // You can change the URL path as needed.
    });

}

Step 4. Add XML Comments
For Swagger to provide descriptions and summaries for your API endpoints, you should add XML comments to your controller methods. To enable XML documentation, go to your project's properties and enable the "Generate XML documentation file" option.

Then, add comments to your controller methods like this:
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using YourNamespace.Models; // Replace with your model namespace
using Microsoft.EntityFrameworkCore;

Author: Peter
[ApiController]
[Route("api/items")]
public class ItemsController : ControllerBase
{
    private readonly YourDbContext _context; // Replace with your DbContext type

    public ItemsController(YourDbContext context)
    {
        _context = context;
    }

    [HttpGet]
    public IActionResult GetItems()
    {
        try
        {
            var items = _context.Items.ToList(); // Assuming "Items" is your DbSet

            if (items == null || items.Count == 0)
            {
                return NoContent(); // Return 204 No Content if no items are found.
            }

            return Ok(items); // Return 200 OK with the list of items.
        }
        catch (Exception ex)
        {
            // Log the exception or handle it accordingly.
            return StatusCode(500, "Internal Server Error"); // Return a 500 Internal Server Error status.
        }
    }
}

Step 5. Run Your API and Access Swagger UI
Build and run your ASP.NET Core Web API project. You can access the Swagger UI by navigating to /api-docs/index.html (or the path you configured in Startup.cs) in your web browser. You should see the API documentation generated by Swagger/OpenAPI.

Now, your ASP.NET Core Web API has comprehensive API documentation generated using Swagger/OpenAPI. Developers can use this documentation to understand and interact with your API effectively.

Dependency Injection (DI) is a design pattern used in software development to establish loosely linked components by allowing dependencies to be injected into a class rather than created within it. This improves code reuse, testability, and maintainability. An Inversion of Control (IoC) container is a tool that manages dependency injection in the context of Dependency Injection.

Step 1: Begin by creating an ASP.NET Core Web API Project.
Launch Visual Studio.
Make a new project in ASP.NET Core Web Application.
Select the API template and make sure ASP.NET Core 3.1 or later is chosen.
Step 2: Establish Dependencies
Assume you wish to build a basic service to manage articles. Here's an example of how you might define your dependencies:
Create the service's interface.

Author: Peter
public interface IArticleService
{
    List<Article> GetAllArticles();
    Article GetArticleById(int id);
}

Implement the service
Author: Peter

public class ArticleService: IArticleService
{
    private List<Article> _articles = new List<Article>
    {
        new Article { Id = 1, Title = "Introduction to Dependency Injection By Peter
        Khan", Content = "..." },
        new Article { Id = 2, Title = "ASP.NET Core Web API Basics", Content = "..." }
    };

    public List<Article> GetAllArticles()
    {
        return _articles;
    }

    public Article GetArticleById(int id)
    {
        return _articles.FirstOrDefault(article => article.Id == id);
    }
}

Step 2. Configure Dependency Injection
In your Startup.cs file, configure the dependency injection container:
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // Register the ArticleService
    services.AddScoped<IArticleService, ArticleService>();
}

Step 3. Create Controller
Create a controller that uses the IArticleService:
[Route("api/[controller]")]
[ApiController]
public class ArticlesController : ControllerBase
{
    private readonly IArticleService _articleService;

    public ArticlesController(IArticleService articleService)
    {
        _articleService = articleService;
    }

    [HttpGet]
    public ActionResult<IEnumerable<Article>> Get()
    {
        var articles = _articleService.GetAllArticles();
        return Ok(articles);
    }

    [HttpGet("{id}")]
    public ActionResult<Article> Get(int id)
    {
        var article = _articleService.GetArticleById(id);
        if (article == null)
            return NotFound();
        return Ok(article);
    }
}

Step 4: Test the API
Run the application and navigate to the appropriate API endpoints, for example:
    GET /api/articles: Retrieve all articles.
    GET /api/articles/{id}: Retrieve an article by its ID.

Remember, this example focuses on setting up a simple ASP.NET Core Web API project with Dependency Injection. For a complete production-ready solution, you'd need to consider error handling, validation, authentication, and other aspects.
Conclusion

We explored the concepts of Dependency Injection (DI) and demonstrated how to integrate DI into an ASP.NET Core Web API project. Dependency Injection is a powerful design pattern that promotes loosely coupled components, better testability, and maintainability. Here's a recap of what we covered:

1. Dependency Injection (DI)
DI is a design pattern that focuses on providing the dependencies a class needs from the outside, rather than creating them internally. This promotes modularity, reusability, and easier testing.

2. Advantages of DI

• Loose Coupling: Components are decoupled, making it easier to replace or update individual parts without affecting the whole system.
• Testability Dependencies can be easily mocked or replaced during testing, leading to more effective unit testing.
• Maintainability: Changes to dependencies can be managed more centrally, making maintenance and updates simpler.

3. Integration with ASP.NET Core Web API

• We created a simple ASP.NET Core Web API project.
• We defined a service interface (IArticleService) and an implementation (ArticleService) to manage articles.
• We configured the dependency injection container in the Startup.cs file using the AddScoped method.
• We created an API controller (ArticlesController) that uses the IArticleService through constructor injection.

4. Testing the API
We ran the application and tested the endpoints using tools like Postman or a web browser.
We observed how the API endpoints interact with the injected service to provide data.

Dependency Injection is a fundamental concept in modern software development, and integrating it into your projects can lead to more maintainable, testable, and scalable applications. As you continue your journey in software development, these principles will prove to be valuable tools in your toolkit.

ASP.NET Core is a robust and adaptable framework for developing web apps and APIs. When developing a RESTful API, it is critical to define a clear and standardized interface for seamless integration with client applications. OpenAPI, formerly Swagger, is a complete solution for creating, documenting, and implementing APIs in ASP.NET Core. In this post, we will look at the best practices for developing an ASP.NET Core REST API with OpenAPI in order to ensure consistency, scalability, and maintainability.

Specify API Requirements
Before we begin development, we must first precisely outline the API's needs. Examine the specific functionalities that must be exposed, the data that must be handled, and the expected replies.

A well-defined API specification will provide a solid foundation for creating our OpenAPI API.

An example of how to define API requirements for a hypothetical "Task Management API" with OpenAPI. Assuming we're creating an API for task management, let's go over some fundamental criteria.

Define the Functions
Specify the features that our API must provide. Consider these essential functionalities in this example, which are listed below.
    Make a task list.
    Obtain information about a certain assignment.
    Make a new task.
    An current task should be updated.
    Remove a task.

Create Data Structures
Define the data structures (models) that will be handled by our API. The models we'll utilize in this example are listed below.
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        description:
          type: string
        dueDate:
          type: string
          format: date

Endpoints must be defined.
Create endpoints for each capability, each with its own set of HTTP methods, request bodies (if any), and response models.
paths:
  /tasks:
    get:
      summary: Get a list of tasks.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
    post:
      summary: Create a new task.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '201':
          description: Task created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'

  /tasks/{taskId}:
    get:
      summary: Get details of a specific task.
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
    put:
      summary: Update an existing task.
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: Task updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
    delete:
      summary: Delete a task.
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: Task deleted successfully.

We provide a clear and disciplined foundation for our API development process by specifying API requirements with OpenAPI. The offered example demonstrates how to create functions, data structures, and endpoints for a "Task Management API." Our actual API design would expand on these ideas, taking into account authentication, error handling, query parameters, and other factors.

Remember that OpenAPI allows us to accurately specify our API needs, making it easier to communicate them to our development team and guarantee that everyone is on the same page before we begin working.

Install OpenAPI Tools
To begin using OpenAPI in ASP.NET Core, we must first install the necessary NuGet packages. Swashbuckle is a pirate.For integrating OpenAPI into our project, we commonly use the ASP.NETCore package. We can use the NuGet Package Manager or the Package Manager Console to install it. The graphic below shows how to install it using the NuGet Package Manager.

NuGet Package Access in ASP.NET Core API Project via Solution Explorer.

The instructions below will show us how to install the Swashbuckle.Manage NuGet Package Manager to install AspNetCore.

Step 2. Initiate by finding the essential "Manage NuGet Packages" option, located at the window's top left corner. Click on "Browse" (highlighted in red) below, and type "Swashbuckle.AspNetCore" in the search field. The search will display various Swashbuckle packages. Choose "Swashbuckle.AspNetCore" (highlighted in blue) and then click the "Install" button (highlighted in green) on the right, next to the chosen package's version. This completes the process.

Enable OpenAPI in Program

As we proceed through this part, our attention will be drawn to enhancing the capabilities of OpenAPI within our application. With this goal in mind, we will begin the process of enabling smooth interaction with OpenAPI. This critical phase is configuring the components required for our application to successfully exploit the power of OpenAPI. We will open up a world of increased documentation and interaction opportunities for our application's API in the future steps.

Configure the OpenAPI services and middleware in the Program.cs file. In the ConfigureServices and Configure methods, add the following code.

Step 1: Set up the Services Method

// Configure Services method
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Best Practices for Creating ASP.NET Core REST API using OpenAPI by Peter", Version = "v1" });
});

Step 2. Configure Method
// Configure method
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Peter Demo API V1");
});

Design API with RESTful Principles
As we embark on the journey of designing our API, it's imperative to embrace the core tenets of RESTful principles. These principles serve as the foundation for creating an API that not only aligns with industry best practices but also facilitates seamless interaction and comprehension.

In this meticulous process, each API endpoint is meticulously crafted, bearing in mind the essence of nouns for resource identification and HTTP verbs for defining actions. This approach lends a level of clarity and consistency that greatly enhances the user experience.

GET /api/users

Action: Retrieve a list of users

Description: This endpoint serves to fetch a comprehensive list of users within the system. It adheres to the RESTful principle of using the HTTP GET verb to retrieve data.

GET /api/users/{id}

Action: Retrieve a specific user by ID

Description: By including the user's unique identifier (ID) in the endpoint, we enable the retrieval of precise user details. The RESTful nature of the design leverages the HTTP GET verb for this purpose.

POST /api/users

Action: Create a new user

Description: This endpoint facilitates the addition of a new user to the system. Employing the HTTP POST verb aligns with RESTful principles, as it signifies the act of creating a resource.

PUT /api/users/{id}

Action: Update an existing user by ID

Description: Through this endpoint, we empower the modification of user information. The specific user is identified by their unique ID. The RESTful approach is upheld by employing the HTTP PUT verb for resource updating.

DELETE /api/users/{id}

Action: Delete a user by ID

Description: By utilizing this endpoint, users can be removed from the system. The targeted user is pinpointed by their ID. In accordance with RESTful principles, the HTTP DELETE verb is employed for resource deletion.

A meticulous approach to API design ensures that our endpoints not only facilitate meaningful actions but also adhere to the robust RESTful framework, enriching our API's usability and comprehensibility.

Use Data Transfer Objects (DTOs)
In our quest to establish seamless communication between clients and the API, we embrace the prowess of Data Transfer Objects (DTOs). These robust constructs serve as data containers, ensuring a structured and controlled exchange of information. Unlike exposing our intricate domain models directly, DTOs assume the role of intermediaries, proficiently governing access to data.

By wielding this strategic approach, we fortify security and mitigate the potential vulnerability of overexposing sensitive data. DTOs epitomize a sophisticated layer that safeguards the integrity of our data and promotes encapsulation.

In this code example, we draw inspiration from the "Task Management API"  we've encountered.

// Original domain model
public class TaskModel
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public DateTime DueDate { get; set; }
}

// Data Transfer Object (DTO)
public class TaskDto
{
    public int Id { get; set; }
    public string Title { get; set; }
    public DateTime DueDate { get; set; }
}

We have created a DTO called TaskDto that encapsulates the communication properties. Note that the Description property is omitted because DTOs provide an efficient method of sharing data. With DTOs, we can optimize the communication process and safeguard sensitive aspects of our domain model by orchestrating a controlled and purpose-driven flow of data.

In the end, Data Transfer Objects represent a strategic move toward robust communication that maintains a delicate balance between access and security.

Validate Request Data
Within the realm of building a resilient API, the cardinal principle of data integrity stands tall. This entails rigorous validation of incoming request data, an indispensable safeguard against potential security vulnerabilities and data discrepancies. The journey toward a secure and reliable API begins with meticulous validation practices underpinned by the synergy of data annotations and custom validation logic.

In the ASP.NET Core landscape, a robust validation paradigm serves as a bulwark against data inconsistencies and unauthorized access. The integration of data validation holds particular significance when harmonized with the power of OpenAPI, effectively ensuring that only legitimate and correctly structured data enters our API.

Step 1. Employing Data Annotations
Data annotations, inherent within ASP.NET Core, emerge as a formidable tool to imbue request data with an aura of reliability. Through the strategic placement of attributes, we assert validation rules that guide the permissible format and constraints of incoming data.

In this code example, we will understand how data annotations can be applied to a DTO in conjunction with our TaskModel example.

using System.ComponentModel.DataAnnotations;

public class TaskDto
{
    public int Id { get; set; }

    [Required(ErrorMessage = "Title is required.")]
    public string Title { get; set; }

    [DataType(DataType.Date)]
    public DateTime DueDate { get; set; }
}

Step 2. Crafting Custom Validation Logic
For scenarios that transcend the realm of data annotations, custom validation logic takes the lead. By extending the ValidationAttribute class, we can create tailor-made validation rules that resonate with our API's unique requirements.

In this code example below, let's consider a custom validation attribute that ensures the due date is in the future.
using System;
using System.ComponentModel.DataAnnotations;

public class FutureDateAttribute : ValidationAttribute
{
    public override bool IsValid(object value)
    {
        if (value is DateTime date)
        {
            return date > DateTime.Now;
        }
        return false;
    }
}

Step 3. Integrating with OpenAPI
The fusion of data validation with OpenAPI crystallizes in the validation constraints, becoming an integral part of our API's documentation. When a client consumes our API through the OpenAPI documentation, they are guided by these constraints, thus minimizing the chances of invalid or erroneous requests.

By coupling data validation with OpenAPI, we're forging a path of data integrity and security that resonates through every interaction with our API. The result is a fortified ecosystem where reliable and validated data forms the bedrock of seamless communication.

In this code example below, the TaskDto class is annotated with data validation attributes, ensuring that the data adheres to defined rules. The CreateTask action method employs ModelState.IsValid to verify the validity of incoming data. If validation fails, a BadRequest response is returned, including the validation errors.
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;

namespace TaskManagementAPI.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...

        [HttpPost]
        public ActionResult<TaskDto> CreateTask(TaskDto taskDto)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }

            // Process valid data and create the task
            // ...

            return Ok("Task created successfully");
        }
    }
    public class TaskDto
    {
        public int Id { get; set; }

        [Required(ErrorMessage = "Title is required.")]
        public string Title { get; set; }

        [DataType(DataType.Date)]
        public DateTime DueDate { get; set; }
    }
}

Remember the keep important when this API is documented using OpenAPI, the validation constraints specified in the TaskDto class become part of the documentation. Clients accessing our API via the OpenAPI documentation are equipped with the knowledge of exactly what data is expected and the validation criteria it must satisfy. This synergy between data validation and OpenAPI augments the reliability of data interactions and ensures a secure communication channel for our API.

Step 4. Leveraging Built-in Validation Features
ASP.NET Core graciously equips developers with a suite of built-in validation features. These intrinsic capabilities work in synergy with OpenAPI, yielding a seamless integration that bolsters the API's robustness.

Within our controller actions, we can invoke the ModelState.IsValid property to effortlessly validate incoming request data. This dynamic property gauges the validity of the request data based on the applied data annotations and custom validation logic.

In this code example, we illustrative excerpt from our controller methods.
[HttpPost]
public ActionResult<TaskDto> CreateTask(TaskDto taskDto)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }

    // Process valid data and create the task
    // ...
}

By embracing this methodology, our API empowers itself to efficiently scrutinize incoming data, weed out discrepancies, and respond to invalid data with grace.

Step 5. Enhancing Data Integrity Through Documentation
When data validation is harmonized with OpenAPI, its impact extends beyond mere code execution. It becomes a cornerstone of our API's documentation. Every validation rule, be it a data annotation or custom logic, is vividly presented within the OpenAPI documentation. This empowers developers, whether they are consuming or contributing to our API, to understand the parameters of valid data exchange.

With meticulous validation, our API's documentation serves as a comprehensive guide for clients to interact securely and effectively. Each interaction is facilitated by a robust validation process that inherently safeguards data integrity.

In essence, the process of data validation, when intertwined with OpenAPI, creates a symbiotic relationship where data integrity, security, and comprehensibility thrive in harmony. This holistic approach ensures that our API not only functions as intended but does so with a profound commitment to security and reliability.

In this code example below, our TaskDto class is annotated with data validation attributes, just as before. Additionally, a custom OpenApiDefinitions class is created to provide information for the OpenAPI documentation. This class is used to define details such as the API's title, version, description, and contact information.
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System;
using System.ComponentModel.DataAnnotations;
namespace TaskManagementAPI.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...
        [HttpPost]
        public ActionResult<TaskDto> CreateTask(TaskDto taskDto)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }

            // Process valid data and create the task
            // ...
            return Ok("Task created successfully");
        }
    }
    public class TaskDto
    {
        public int Id { get; set; }

        [Required(ErrorMessage = "Title is required.")]
        public string Title { get; set; }

        [DataType(DataType.Date)]
        public DateTime DueDate { get; set; }
    }

    // OpenAPI documentation
    public class OpenApiDefinitions
    {
        public OpenApiInfo Info {

By integrating data validation with OpenAPI, we ensure that the validation rules are an integral part of our API's documentation. When clients access our API through the OpenAPI documentation, they have a clear understanding of the validation criteria for each data attribute. This alignment between validation and documentation fosters secure and effective interactions, reinforcing data integrity throughout the API ecosystem.

Step 6. Handling Validation Errors Gracefully
Validation is a two-way street. While it ensures data integrity, it also necessitates efficient error handling when data doesn't meet the defined criteria. This engagement between validation and error handling is crucial to create a user-friendly experience for clients.

Within our controller actions, we can further customize our responses to address validation errors. This provides clients with clear insights into what went wrong and how they can rectify it.
[HttpPost]
public ActionResult<TaskDto> CreateTask(TaskDto taskDto)
{
    if (!ModelState.IsValid)
    {
        var validationErrors = ModelState.Where(e => e.Value.Errors.Any())
                                          .ToDictionary(k => k.Key, v => v.Value.Errors.Select(e => e.ErrorMessage));
        return BadRequest(validationErrors);
    }

    // Process valid data and create the task
    // ...
}

By enriching the response with detailed error messages, we empower clients to rectify the issues efficiently, leading to smoother interactions and a positive user experience.

Step 7.The Power of Continuous Improvement
The beauty of embracing data validation within the OpenAPI context is its adaptability. As our API evolves, so can our validation rules. With OpenAPI serving as the documentation layer, changes in validation are seamlessly reflected, providing clients with up-to-date expectations for data exchange.

By nurturing a culture of continuous improvement, we ensure that our API's validation mechanisms align with the ever-changing landscape of data security and integrity.

In this code example below, we've introduced a custom validation attribute FutureDateAttribute that validates if a date is in the future. This showcases how the validation logic can evolve and adapt to changing requirements.
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System;
using System.ComponentModel.DataAnnotations;
namespace TaskManagementAPI.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...
        [HttpPost]
        public ActionResult<TaskDto> CreateTask(TaskDto taskDto)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            // Process valid data and create the task
            // ...
            return Ok("Task created successfully");
        }
    }

    public class TaskDto
    {
        public int Id { get; set; }
        [Required(ErrorMessage = "Title is required.")]
        public string Title { get; set; }
        [DataType(DataType.Date)]
        [FutureDate(ErrorMessage = "Due date must be in the future.")]
        public DateTime DueDate { get; set; }
    }
    // Custom validation attribute for future date
    public class FutureDateAttribute : ValidationAttribute
    {
        public override bool IsValid(object value)
        {
            if (value is DateTime date)
            {
                return date > DateTime.Now;
            }
            return false;
        }
    }
    // OpenAPI documentation
    public class OpenApiDefinitions
    {
        public OpenApiInfo Info { get; } = new OpenApiInfo
        {
            Title = "Task Management API",
            Version = "v1",
            Description = "An API for managing tasks with data validation integrated.",
            Contact = new OpenApiContact
            {
                Name = "Our Name",
                Email = "[email protected]"
            }
        };
    }
}

By nurturing a culture of continuous improvement, our API's validation mechanisms remain in alignment with the dynamic landscape of data security and integrity. As we update our validation rules, OpenAPI's role as a documentation layer ensures that clients are always informed of the latest expectations for data exchange. This dynamic harmony between validation and documentation enhances the reliability of our API over time.

It is the journey of data validation within the realm of OpenAPI a holistic endeavor that encapsulates meticulous design, execution, documentation, and adaptability. By weaving together these facets, we create an API ecosystem that's fortified by validation, poised for secure data exchanges, and dedicated to offering a refined experience to both clients and developers.

Document API with Descriptive Comments
In the meticulous endeavor of crafting an API that stands as a beacon of clarity and functionality, the act of documentation assumes a pivotal role. At the heart of this process lies the use of descriptive comments—a mechanism through which we articulate the essence of our API endpoints, parameters, and responses. These comments don't merely serve as annotations; they are the pillars upon which the comprehensibility and usability of our API stand. The symbiosis between these descriptive comments and the power of OpenAPI furnishes an automated mechanism for generating API documentation. With each carefully crafted comment, we set the stage for developers to seamlessly comprehend the intricacies of interacting with our API.

Step 1. Endpoints and Parameters
Every API journey commences with endpoints—gateways to functionality. Enriching these gateways with descriptive comments acts as a guide for developers navigating through the labyrinth of capabilities. Take, for instance, the scenario of retrieving a user's details.

In this code example below, the <summary> tag provides a concise summary of the endpoint's purpose. The <param> tag expounds on the parameters' roles, and the <returns> tag elucidates the anticipated response.
/// <summary>
/// Retrieve a specific user's details by ID.
/// </summary>
/// <param name="id">The ID of the user to retrieve.</param>
/// <returns>The details of the requested user.</returns>
[HttpGet("{id}")]
public ActionResult<UserDto> GetUser(int id)
{
    // Implement your logic here
}

Step 2. Responses
Responses are the soul of API interactions—they hold the outcomes developers eagerly anticipate. Elaborating on these outcomes through descriptive comments crystallizes the understanding. Consider the act of creating a new user. Once more, the descriptive comments underpin the API interaction with insights into its purpose, the nature of the request payload, and the response to be expected as the code example below shows us this.

Step 3. Harnessing OpenAPI's Magic
As these descriptive comments enrobe our API, they forge a pathway for OpenAPI to work its magic. As developers interact with our API documentation, OpenAPI diligently translates these comments into a coherent and structured resource. The documentation reflects the essence of every endpoint, parameter, and response, extending a helping hand to developers striving to navigate the intricacies of our API.

In this code example, we have the comments above; the CreateTask method provides a clear description of the endpoint's purpose, its parameters, and its expected response. When we integrate OpenAPI into our ASP.NET Core application, it utilizes these comments to automatically generate structured API documentation. This documentation helps developers understand the API's intricacies, ensuring that they can interact with it effectively and confidently.
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System;
using System.ComponentModel.DataAnnotations;

namespace TaskManagementAPI.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...

        /// <summary>
        /// Create a new task.
        /// </summary>
        /// <param name="taskDto">The task's information for creation.</param>
        /// <returns>A confirmation of the task's successful creation.</returns>
        [HttpPost]
        public ActionResult<string> CreateTask(TaskDto taskDto)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            // Implement your logic here
            // ...
            return Ok("Task created successfully");
        }
        // Other endpoints and actions
        /// <summary>
        /// Data Transfer Object (DTO) for task information.
        /// </summary>
        public class TaskDto
        {
            public int Id { get; set; }
            [Required(ErrorMessage = "Title is required.")]
            public string Title { get; set; }
            [DataType(DataType.Date)]
            [FutureDate(ErrorMessage = "Due date must be in the future.")]
            public DateTime DueDate { get; set; }
        }
        /// <summary>
        /// Custom validation attribute for future date.
        /// </summary>
        public class FutureDateAttribute : ValidationAttribute
        {
            public override bool IsValid(object value)
            {
                if (value is DateTime date)
                {
                    return date > DateTime.Now;
                }
                return false;
            }
        }
        // OpenAPI documentation
        public class OpenApiDefinitions
        {
            public OpenApiInfo Info { get; } = new OpenApiInfo
            {
                Title = "Peter Task Management API",
                Version = "v1",
                Description = "An API for managing tasks with comprehensive documentation.",
                Contact = new OpenApiContact
                {
                    Name = "Peter",
                    Email = "[email protected]"
                }
            };
        }
    }
}

Step 4. Empowering Developers, Amplifying Usability
With each comment etched in precision, the resulting documentation becomes an invaluable resource. Developers, whether novices or veterans, are equipped with the knowledge necessary to seamlessly engage with our API. Descriptive comments transcend mere code; they encapsulate our API's essence and communicate it to those seeking to harness its power.

In this code example below, we have carefully crafted comments that transcend the boundaries of mere code annotations. They encapsulate the essence of our API's functionality, clarifying its purpose and the expected interactions. Developers, regardless of their experience level, are armed with invaluable insights as they traverse our API documentation. This empowers them to harness our API's capabilities effectively and fully unlock its potential.
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System;
using System.ComponentModel.DataAnnotations;
namespace TaskManagementAPI.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...
        /// <summary>
        /// Create a new task.
        /// </summary>
        /// <param name="taskDto">The task's information for creation.</param>
        /// <returns>A confirmation of the task's successful creation.</returns>
        [HttpPost]
        public ActionResult<string> CreateTask(TaskDto taskDto)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            // Implement your logic here
            // ...
            return Ok("Task created successfully");
        }
        // Other endpoints and actions
        /// <summary>
        /// Data Transfer Object (DTO) for task information.
        /// </summary>
        public class TaskDto
        {
            public int Id { get; set; }
            [Required(ErrorMessage = "Title is required.")]
            public string Title { get; set; }
            [DataType(DataType.Date)]
            [FutureDate(ErrorMessage = "Due date must be in the future.")]
            public DateTime DueDate { get; set; }
        }
        /// <summary>
        /// Custom validation attribute for future date.
        /// </summary>
        public class FutureDateAttribute : ValidationAttribute
        {
            public override bool IsValid(object value)
            {
                if (value is DateTime date)
                {
                    return date > DateTime.Now;
                }
                return false;
            }
        }
        // OpenAPI documentation
        public class OpenApiDefinitions
        {
            public OpenApiInfo Info { get; } = new OpenApiInfo
            {
                Title = "Peter Task Management API",
                Version = "v1",
                Description = "An API for managing tasks with comprehensive documentation.",
                Contact = new OpenApiContact
                {
                    Name = "Peter",
                    Email = "[email protected]"
                }
            };
        }
    }
}

The integration of descriptive comments with OpenAPI nurtures a realm where developers can immerse themselves in the API's essence, thereby fostering a harmonious union between comprehension and usability. As a result, the API becomes a conduit for innovation, enabling developers to channel their creativity with the confidence that they're interacting with a well-documented and empowering resource.

In the intricate dance between descriptive comments and OpenAPI, we orchestrate an experience of unimpeded comprehension. This experience, in turn, fuels the vitality of our API and beckons developers to embark on journeys of innovation, all while enjoying the robust support of a comprehensible and fully-documented API ecosystem.

Versioning Our API
As we embark on the journey of architecting a robust and adaptable API, the importance of versioning takes center stage. The art of versioning bestows upon us the ability to uphold backward compatibility while leaving the gateway open for future enhancements. This process ensures that the intricate tapestry of our API continues to serve both current and future demands. One of the potent methods to wield versioning lies in the inclusion of version numbers—a beacon guiding both developers and clients through the labyrinth of iterations.

Step 1. Embracing the Versioning Paradigm
The foundation of versioning is rooted in a simple yet profound principle: to clearly demarcate each iteration of our API. By assigning a version number to our API, we transform it into a cohesive entity that evolves while preserving its historical roots.

In this code example below, we have the versioning paradigm embraced by including version number v1 in the route of the TasksController class. This version number clearly demarcates the iteration of the API, turning it into a distinct and cohesive entity. As our API evolves, we can introduce new versions, such as v2, while preserving the historical roots of previous versions. This way, our API remains adaptable and backward-compatible, catering to both existing and potential consumers.

using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System;
namespace TaskManagementAPI.Controllers
{
    [ApiController]
    [Route("api/v1/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...
        [HttpGet]
        public ActionResult<IEnumerable<TaskDto>> GetTasks()
        {
            // Implement your logic here
        }
        // Other endpoints and actions
        public class TaskDto
        {
            public int Id { get; set; }
            public string Title { get; set; }
            public DateTime DueDate { get; set; }
        }
        // OpenAPI documentation
        public class OpenApiDefinitions
        {
            public OpenApiInfo Info { get; } = new OpenApiInfo
            {
                Title = "Peter Task Management API",
                Version = "v1",
                Description = "An API for managing tasks with version 1.",
                Contact = new OpenApiContact
                {
                    Name = "Peter",
                    Email = "[email protected]"
                }
            };
        }
    }
}

Step 2. Selecting the Path of URL-Based Versioning
The landscape of versioning beckons us with diverse routes, each tailored to specific use cases. Among these, the URL-based approach emerges as an epitome of simplicity and adherence to RESTful practices. In the code example below, let's suppose we have an API for tasks, and we're venturing into versioning. Here's how the URL-based approach looks in practice.

[ApiController]
[Route("api/[controller]")]
public class TasksController : ControllerBase
{
    // ...
}

[ApiController]
[Route("api/v1/[controller]")]
public class TasksController : ControllerBase
{
    // ...
}

In this code example above, we have the addition of /v1/ in the route explicitly indicating the API's version. This way, the existing clients continue to interact with the previous version, while newer clients can access the enhanced version seamlessly.

Step 3. Bestowing Client-Friendly Simplicity
The beauty of the URL-based approach lies in its innate simplicity. Clients intuitively navigate through the API, with version numbers acting as signposts. The result is a streamlined experience that minimizes friction and maximizes engagement.

In this code example, we have the versioning approach demonstrated by including the version number v1 in the route of the TasksController class. This version number serves as a signpost for clients as they navigate through the API. By intuitively including the version in the URL, clients experience a seamless and straightforward interaction. The result is a streamlined experience that reduces friction and encourages engagement. This simplicity in navigation enhances the usability of the API and ensures that clients can easily discover and leverage the features provided by each version.
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System;
namespace TaskManagementAPI.Controllers
{
    [ApiController]
    [Route("api/v1/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...
        [HttpGet]
        public ActionResult<IEnumerable<TaskDto>> GetTasks()
        {
            // Implement your logic here
        }
        // Other endpoints and actions
        public class TaskDto
        {
            public int Id { get; set; }
            public string Title { get; set; }
            public DateTime DueDate { get; set; }
        }
        // OpenAPI documentation
        public class OpenApiDefinitions
        {
            public OpenApiInfo Info { get; } = new OpenApiInfo
            {
                Title = "Peter Task Management API",
                Version = "v1",
                Description = "An API for managing tasks with version 1.",
                Contact = new OpenApiContact
                {
                    Name = "Peter",
                    Email = "[email protected]"
                }
            };
        }
    }
}

Step 4. Adaptability for the Future
Versioning isn't a mere strategy; it's a roadmap for evolution. As our API matures, new features and refinements will emerge. With the URL-based versioning approach, accommodating these changes becomes a natural progression. New iterations can be gracefully introduced, maintaining a harmonious balance between innovation and compatibility.

In this code example below, we have the API initially designed with version 1 using the URL-based versioning approach (api/v1/[controller]). As the API evolves, a new version (v2) is introduced by creating a new controller class (TasksControllerV2) with an updated route (api/v2/[controller]). This approach allows for the graceful introduction of new features and refinements while maintaining compatibility with existing clients. Each version has its own set of endpoints, actions, and DTOs, ensuring a harmonious balance between innovation and compatibility.
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System;
namespace TaskManagementAPI.Controllers
{
    // Original version (v1)
    [ApiController]
    [Route("api/v1/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...
        [HttpGet]
        public ActionResult<IEnumerable<TaskDto>> GetTasks()
        {
            // We Implementation our logic here
        }
        // Other endpoints and actions
        public class TaskDto
        {
            public int Id { get; set; }
            public string Title { get; set; }
            public DateTime DueDate { get; set; }
        }
        // OpenAPI documentation
        public class OpenApiDefinitions
        {
            public OpenApiInfo Info { get; } = new OpenApiInfo
            {
                Title = "Peter Task Management API",
                Version = "v1",
                Description = "An API for managing tasks with version 1.",
                Contact = new OpenApiContact
                {
                    Name = "Peter",
                    Email = "[email protected]"
                }
            };
        }
    }
    // New version (v2) introduced
    [ApiController]
    [Route("api/v2/[controller]")]
    public class TasksControllerV2 : ControllerBase
    {
        // ...

        [HttpGet]
        public ActionResult<IEnumerable<TaskDtoV2>> GetTasks()
        {
            // Implementation our logic here for version 2
        }

        // Other endpoints and actions specific to v2
        public class TaskDtoV2
        {
            public int Id { get; set; }
            public string Title { get; set; }
            public DateTime DueDate { get; set; }
            public string Priority { get; set; } // Additional property in v2
        }
        // OpenAPI documentation for version 2
        public class OpenApiDefinitionsV2
        {
            public OpenApiInfo Info { get; } = new OpenApiInfo
            {
                Title = "Peter Task Management API",
                Version = "v2",
                Description = "An API for managing tasks with version 2.",
                Contact = new OpenApiContact
                {
                    Name = "Peter",
                    Email = "[email protected]"
                }
            };
        }
    }
}

Step 5. Harnessing Header-Based Versioning
While the URL-based approach garners favor for its simplicity, another avenue is header-based versioning. This method involves specifying the version number in the request header. While it offers flexibility, it may require more client-side effort to incorporate the header. Below is a code example showing us the Header-based versioning.
// Header-based versioning
[ApiController]
[Route("api/[controller]")]
public class TasksController : ControllerBase
{
    // ...
    [HttpGet]
    [ApiVersion("1.0")] // Version specified in the header
    public ActionResult<IEnumerable<Task>> GetTasks()
    {
        // Implementation of your logic here
    }
}

Step 6. In Summation
Versioning our API encapsulates the ethos of evolution within its framework. By employing version numbers in URLs or headers, we extend an olive branch to both current and future stakeholders. We align ourselves with RESTful principles, ensuring compatibility and simplicity for clients. This meticulous approach doesn't just enhance our API; it nurtures an ecosystem that thrives on the continuous synergy between innovation and accessibility.

In this code example below, we have the API versioned using URL-based versioning (api/v1/[controller] and api/v2/[controller]). Each version is encapsulated within its own controller class (TasksController and TasksControllerV2). Additionally, custom OpenAPI documentation classes (OpenApiDefinitions and OpenApiDefinitionsV2) are defined to describe each version of the API. The custom ApiVersionAttribute demonstrates how we can create our own versioning attributes to encapsulate versioning behavior, providing a seamless way to apply versioning across multiple controllers. This approach aligns with RESTful principles, allowing for compatibility and simplicity for clients while fostering a dynamic ecosystem that thrives on innovation and accessibility.
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System;
namespace TaskManagementAPI.Controllers
{
    // Version 1
    [ApiController]
    [Route("api/v1/[controller]")]
    public class TasksController : ControllerBase
    {
        // ...
    }
    // Version 2
    [ApiController]
    [Route("api/v2/[controller]")]
    public class TasksControllerV2 : ControllerBase
    {
        // ...
    }
    // OpenAPI documentation for version 1
    public class OpenApiDefinitions
    {
        public OpenApiInfo Info { get; } = new OpenApiInfo
        {
            Title = "Peter Task Management API",
            Version = "v1",
            Description = "An API for managing tasks with version 1.",
            Contact = new OpenApiContact
            {
                Name = "Peter",
                Email = "[email protected]"
            }
        };
    }

    // OpenAPI documentation for version 2
    public class OpenApiDefinitionsV2
    {
        public OpenApiInfo Info { get; } = new OpenApiInfo
        {
            Title = "Peter Task Management API",
            Version = "v2",
            Description = "An API for managing tasks with version 2.",
            Contact = new OpenApiContact
            {
                Name = "Peter",
                Email = "[email protected]"
            }
        };
    }
    // Custom versioning attribute
    [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
    public class ApiVersionAttribute : RouteAttribute
    {
        public ApiVersionAttribute(string version) : base($"api/{version}/[controller]")
        {
        }
    }
}