DEV Community: Zied Rebhi

A Comprehensive Guide to Interceptors in EF Core

Zied Rebhi — Fri, 13 Dec 2024 19:48:07 +0000

Entity Framework Core (EF Core) is a powerful and flexible Object-Relational Mapper (ORM) for .NET developers. Among its features, interceptors provides a mechanism to tap into the EF Core pipeline, allowing developers to inspect, modify, or augment EF Core operations. This guide explains interceptors, how they work, and their practical applications with examples. We’ll also explore the benefits and pitfalls of using interceptors.

What Are Interceptors in EF Core?

Interceptors in EF Core are hooks into the internal processes of EF Core. They allow developers to execute custom logic during various EF Core operations such as database commands, queries, or save operations.

Interceptors work similarly to middleware. They intercept operations, giving you a chance to:

Log data
Validate operations
Modify behavior

Unlike EF Core events (e.g., SaveChanges or Querying), interceptors are more granular and designed for low-level access to EF Core operations.

Key Types of Interceptors

EF Core provides severals built-in interfaces to define interceptors:

IDbCommandInterceptor: For database command execution.
ISaveChangesInterceptor: For intercepting SaveChanges operations.
IQueryExpressionInterceptor: For intercepting LINQ query expressions.
IConnectionInterceptor: For database connection operations.
ITransactionInterceptor: For intercepting transaction-related operations.

Setting Up a Sample .NET Web API with EF Core

Let’s start by creating a clean .NET Web API project using EF Core and then integrate interceptors.

Step 1: Create a New Web API Project

Run the following commands to create a new .NET Web API project

mkdir EfCoreInterceptors
cd EfCoreInterceptors
dotnet new webapi

Step 2: Add EF Core and Database Provider

Install EF Core and a database provider, such as SQL Server:

dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

Step 3: Create the DbContext and Entity Classes
Define a Product entity and AppDbContext:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public bool IsDeleted { get; set; } // For soft delete functionality
    public DateTime CreatedAt { get; set; }
    public DateTime? UpdatedAt { get; set; }
}

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    public DbSet<Product> Products { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Product>().HasQueryFilter(p => !p.IsDeleted); // Soft delete query filter
    }
}

Step 4: Configure the Database Connection

Update Program.cs to configure the database connection:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseAuthorization();

app.MapControllers();

app.Run();

Add a connection string to appsettings.json:

"ConnectionStrings": {
  "DefaultConnection": "Server=localhost;Database=EfCoreDemo;Trusted_Connection=True;"
}

Adding Interceptors

Example 1: Logging SQL Queries with IDbCommandInterceptor

Let’s add a simple interceptor to log all SQL commands executed by EF Core.

using Microsoft.EntityFrameworkCore.Diagnostics;
using System.Data.Common;

public class SqlLoggingInterceptor : IDbCommandInterceptor
{
    public override DbCommand CommandCreated(CommandEndEventData eventData, DbCommand result)
    {
        Console.WriteLine($"SQL Command Created: {result.CommandText}");
        return result;
    }

    public override InterceptionResult<DbDataReader> ReaderExecuting(DbCommand command, CommandEventData eventData, InterceptionResult<DbDataReader> result)
    {
        Console.WriteLine($"Executing SQL Command: {command.CommandText}");
        return result;
    }
}

Registering the Interceptor

public class AppDbContext : DbContext
{
    private readonly IDbCommandInterceptor _sqlLoggingInterceptor;

    public AppDbContext(DbContextOptions<AppDbContext> options, IDbCommandInterceptor sqlLoggingInterceptor)
        : base(options)
    {
        _sqlLoggingInterceptor = sqlLoggingInterceptor;
    }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.AddInterceptors(_sqlLoggingInterceptor);
    }

    public DbSet<Product> Products { get; set; }
}

Update Program.cs to inject the interceptor:

builder.Services.AddSingleton<IDbCommandInterceptor, SqlLoggingInterceptor>();

Example 2: Detecting Slow Queries

This interceptor logs queries that take longer than a specified threshold and triggers an alert (e.g., sends an email or logs to an external monitoring service) for production monitoring.

using System.Diagnostics;

public class SlowQueryInterceptor : IDbCommandInterceptor
{
    private readonly TimeSpan _threshold = TimeSpan.FromMilliseconds(500);
    private readonly IMonitoringService _monitoringService;

    public SlowQueryInterceptor(IMonitoringService monitoringService)
    {
        _monitoringService = monitoringService;
    }

    public override InterceptionResult<DbDataReader> ReaderExecuting(DbCommand command, CommandEventData eventData, InterceptionResult<DbDataReader> result)
    {
        var stopwatch = Stopwatch.StartNew();
        try
        {
            return base.ReaderExecuting(command, eventData, result);
        }
        finally
        {
            stopwatch.Stop();
            if (stopwatch.Elapsed > _threshold)
            {
                var message = $"Slow Query Detected: {command.CommandText} took {stopwatch.ElapsedMilliseconds} ms";
                Console.WriteLine(message);

                // Trigger alert to monitoring service
                _monitoringService.LogSlowQuery(message);
            }
        }
    }
}

Implementation Notes

IMonitoringService: Define a monitoring service interface to abstract the alerting mechanism. For example:

public interface IMonitoringService
{
    void LogSlowQuery(string message);
}

Concrete Monitoring Service: Implement the interface using tools like email services or external monitoring platforms (e.g., Application Insights, or custom email notifications).

public class EmailMonitoringService : IMonitoringService
{
    public void LogSlowQuery(string message)
    {
        // Implement email or external logging here
        Console.WriteLine($"Alert sent: {message}");
    }
}

builder.Services.AddSingleton<IMonitoringService, EmailMonitoringService>();
builder.Services.AddSingleton<IDbCommandInterceptor, SlowQueryInterceptor>();

This interceptor logs queries that take longer than a specified threshold.

public class SlowQueryInterceptor : IDbCommandInterceptor
{
    private readonly TimeSpan _threshold = TimeSpan.FromMilliseconds(500);

    public override InterceptionResult<DbDataReader> ReaderExecuting(DbCommand command, CommandEventData eventData, InterceptionResult<DbDataReader> result)
    {
        var stopwatch = Stopwatch.StartNew();
        var readerResult = base.ReaderExecuting(command, eventData, result);
        stopwatch.Stop();

        if (stopwatch.Elapsed > _threshold)
        {
            Console.WriteLine($"Slow Query Detected: {command.CommandText} took {stopwatch.ElapsedMilliseconds} ms");
        }

        return readerResult;
    }
}

Example 3: Implementing Soft Delete with ISaveChangesInterceptor

Soft delete logic can be particularly useful in multi-tenant systems or in cases where complex relationships require handling cascading deletes safely. This example shows how to intercept _SaveChanges _to implement soft delete functionality while considering these scenarios.

public class SoftDeleteInterceptor : ISaveChangesInterceptor
{
    public override int SavingChanges(DbContextEventData eventData, InterceptionResult<int> result)
    {
        var context = eventData.Context;
        if (context == null) return base.SavingChanges(eventData, result);

        foreach (var entry in context.ChangeTracker.Entries())
        {
            // Handle entities with IsDeleted property
            if (entry.Entity is ISoftDeletable softDeletableEntity && entry.State == EntityState.Deleted)
            {
                entry.State = EntityState.Modified;
                softDeletableEntity.IsDeleted = true;

                // Update related entities if required for complex relationships
                if (entry.Entity is ITenantEntity tenantEntity)
                {
                    HandleTenantSpecificLogic(context, tenantEntity);
                }
            }
        }

        return base.SavingChanges(eventData, result);
    }

    private void HandleTenantSpecificLogic(DbContext context, ITenantEntity tenantEntity)
    {
        // Example: Ensure related tenant-specific records are soft-deleted or flagged appropriately
        var relatedEntities = context.ChangeTracker.Entries()
            .Where(e => e.Entity is IRelatedEntity && ((IRelatedEntity)e.Entity).TenantId == tenantEntity.TenantId);

        foreach (var relatedEntity in relatedEntities)
        {
            if (relatedEntity.State == EntityState.Deleted)
            {
                relatedEntity.State = EntityState.Modified;
                ((IRelatedEntity)relatedEntity.Entity).IsDeleted = true;
            }
        }
    }
}

Considerations for Multi-Tenant Systems:

Tenant Isolation: Ensure that soft delete operations respect tenant boundaries to avoid accidental cross-tenant modifications.
** Query Filters:** Use global query filters to exclude soft-deleted entities based on the tenant context.

modelBuilder.Entity<Product>().HasQueryFilter(p => !p.IsDeleted && p.TenantId == currentTenantId);

Register the Interceptor

builder.Services.AddSingleton<ISaveChangesInterceptor, SoftDeleteInterceptor>();

Example 4: Auditing Changes with ISaveChangesInterceptor

Track who created or updated entitiess.

public class AuditInterceptor : ISaveChangesInterceptor
{
    public override int SavingChanges(DbContextEventData eventData, InterceptionResult<int> result)
    {
        var context = eventData.Context;
        if (context == null) return base.SavingChanges(eventData, result);

        foreach (var entry in context.ChangeTracker.Entries<Product>())
        {
            if (entry.State == EntityState.Added)
            {
                entry.CurrentValues["CreatedAt"] = DateTime.UtcNow;
            }

            if (entry.State == EntityState.Modified)
            {
                entry.CurrentValues["UpdatedAt"] = DateTime.UtcNow;
            }
        }

        return base.SavingChanges(eventData, result);
    }
}

Example 5: Data Masking for Sensitive Data

Mask sensitive data when it’s queried from the database.

public class DataMaskingInterceptor : IDbCommandInterceptor
{
    public override InterceptionResult<DbDataReader> ReaderExecuted(DbCommand command, CommandExecutedEventData eventData, DbDataReader result)
    {
        // Example: Masking sensitive fields like SSN or Email
        var maskedReader = new MaskedDbDataReader(result);
        return InterceptionResult<DbDataReader>.Success(maskedReader);
    }
}

public class MaskedDbDataReader : DbDataReader
{
    private readonly DbDataReader _innerReader;

    public MaskedDbDataReader(DbDataReader innerReader)
    {
        _innerReader = innerReader;
    }

    public override string GetString(int ordinal)
    {
        var columnName = _innerReader.GetName(ordinal);
        var value = _innerReader.GetString(ordinal);

        if (columnName == "SSN")
        {
            return "***-**-****"; // Mask SSN
        }

        if (columnName == "Email")
        {
            return "****@example.com"; // Mask email
        }

        return value;
    }

    // Delegate all other methods to _innerReader
    public override bool Read() => _innerReader.Read();
    // Implement other necessary methods...
}

Example 6: Retry Logic for Transient Failures

Handle transient failures (e.g., database connection drops) with retry logic.

public class RetryInterceptor : IDbCommandInterceptor
{
    private const int MaxRetryCount = 3;

    public override InterceptionResult<DbDataReader> ReaderExecuting(DbCommand command, CommandEventData eventData, InterceptionResult<DbDataReader> result)
    {
        for (int retry = 0; retry < MaxRetryCount; retry++)
        {
            try
            {
                return base.ReaderExecuting(command, eventData, result);
            }
            catch (DbException ex)
            {
                if (retry == MaxRetryCount - 1) throw;
                Console.WriteLine($"Retrying due to transient failure: {ex.Message}");
            }
        }

        return result;
    }
}

Advantages of Interceptors

Centralized Logic: Write logic once and apply it across the DbContext.
Enhanced Debugging: Log queries, commands, and EF Core operations for better diagnostics.
Custom Behavior: Modify or validate EF Core operations without polluting business logic.
Security: Enforce rules such as preventing sensitive data deletion or unauthorized queries.

Potential Pitfalls

Complexity: Interceptors introduce additional complexity and may confuse developers unfamiliar with the EF Core pipeline.
Performance Overhead: Excessive processing within interceptors can degrade application performance.
Maintenance Challenges: Changes to EF Core or application requirements may necessitate updates to interceptors.
Limited Scope: Some interceptors, like IDbCommandInterceptor, provide access only at a low level, requiring knowledge of database internals.

Best Practices

Use Interceptors Sparingly: Only use them for cross-cutting concerns or operations that cannot be handled elsewhere.
Test Extensively: Ensure interceptors do not introduce unintended side effect.
Log Strategically: Avoid over-logging to maintain performances.
Keep Code Readable: Use clear and concise logic in interceptor.

Thank you .

Securing a .NET API C#: API Key, Basic Authentication, and JWT 🔒

Zied Rebhi — Thu, 12 Dec 2024 19:17:33 +0000

When developing a .NET API, ensuring secure access control is critical to protect sensitive data and resources. Several methods are available, including API Key Authentication, Basic Authentication, and JSON Web Tokens (JWT). Each has its use case and security implications. This article explores how to implement these methods in a .NET API.

Sample Payment API

Here is a basic example of a Payment API with CRUD operations:
You can find the full code in this GitHub Repo

[Route("api/[controller]")]
    [ApiController]
    public class PaymentsController : ControllerBase
    {
        // Get all payments
        [HttpGet]
        public ActionResult<IEnumerable<Payment>> GetPayments()
        {
            var payments = PaymentRepository.GetPayments();
            return Ok(payments);
        }

        // Get a payment by ID
        [HttpGet("{id}")]
        public ActionResult<Payment> GetPayment(int id)
        {
            var payment = PaymentRepository.GetPaymentById(id);
            if (payment == null)
                return NotFound();
            return Ok(payment);
        }

        // Add a new payment
        [HttpPost]
        public ActionResult<Payment> PostPayment([FromBody] Payment payment)
        {
            if (payment == null)
                return BadRequest();

            payment.Id = PaymentRepository.GetPayments().Max(p => p.Id) + 1;  // Auto-increment ID
            PaymentRepository.AddPayment(payment);
            return CreatedAtAction(nameof(GetPayment), new { id = payment.Id }, payment);
        }

        // Update an existing payment
        [HttpPut("{id}")]
        public IActionResult PutPayment(int id, [FromBody] Payment payment)
        {
            if (payment == null)
                return BadRequest();

            PaymentRepository.UpdatePayment(id, payment);
            return NoContent();
        }

        // Delete a payment
        [HttpDelete("{id}")]
        public IActionResult DeletePayment(int id)
        {
            var payment = PaymentRepository.GetPaymentById(id);
            if (payment == null)
                return NotFound();

            PaymentRepository.DeletePayment(id);
            return NoContent();
        }
    }

1. API Key Authentication

API Key Authentication is a simple mechanism where clients send a unique key with their requests. The server validates this key to grant access.

Required Package

No additional package is required for API Key Authentication.

Implementation:

Generate an API Key:

Create a secure and unique key for each client. Store these keys securely in your environment variables or app Settings etc to get it .

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApiKey": "SuperSecretApiKey12345"
}

Middleware for Validation:

Add middleware to validate the API key in incoming requests.

public class ApiKeyMiddleware
    {
        private readonly RequestDelegate _next;
        private const string ApiKeyHeaderName = "X-API-KEY";

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

        public async Task InvokeAsync(HttpContext context, IConfiguration configuration)
        {
            if (!context.Request.Headers.TryGetValue(ApiKeyHeaderName, out var extractedApiKey))
            {
                context.Response.StatusCode = 401;
                await context.Response.WriteAsync("API Key is missing.");
                return;
            }

            var apiKey = configuration.GetValue<string>("ApiKey");

            if (!apiKey.Equals(extractedApiKey))
            {
                context.Response.StatusCode = 403;
                await context.Response.WriteAsync("Unauthorized client.");
                return;
            }

            await _next(context);
        }
    }

    public static class ApiKeyMiddlewareExtensions
    {
        public static IApplicationBuilder UseApiKeyMiddleware(this IApplicationBuilder builder)
        {
            return builder.UseMiddleware<ApiKeyMiddleware>();
        }
    }

Register Middleware: In your program.cs file :

app.UseHttpsRedirection();
app.UseAuthorization();
// Use API Key 
app.UseApiKeyMiddleware(); //add this
app.MapControllers();

Swagger Configuration:

To let your clients test the secured API throw Swagger , you should configure it :

// Add Swagger with API Key configuration
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Payment API - API Key", Version = "v1" });
    c.AddSecurityDefinition("ApiKey", new OpenApiSecurityScheme
    {
        Name = "X-API-KEY",
        Type = SecuritySchemeType.ApiKey,
        In = ParameterLocation.Header,
        Description = "Enter your API Key in the header."
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "ApiKey"
                }
            },
            new string[] { }
        }
    });
});
var app = builder.Build();

When Api key is valid , you will be authorized to use the Api's endpoints else you will get 401 error

2. Basic Authentication

Basic Authentication requires the client to send a username and password in the Authorization header. This method is suitable for internal APIs or development environments.

Required Package

Install the following NuGet package:

Microsoft.AspNetCore.Authentication

Implementation:

Create Authentication Handler:

public class BasicAuthMiddleware
    {
        private readonly RequestDelegate _next;

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

        public async Task InvokeAsync(HttpContext context)
        {
            if (!context.Request.Headers.TryGetValue("Authorization", out var authorizationHeader))
            {
                context.Response.StatusCode = 401;
                context.Response.Headers["WWW-Authenticate"] = "Basic realm=\"PaymentApi\"";
                await context.Response.WriteAsync("Authorization header is missing.");
                return;
            }

            var authHeader = AuthenticationHeaderValue.Parse(authorizationHeader);
            var credentialBytes = Convert.FromBase64String(authHeader.Parameter ?? string.Empty);
            var credentials = Encoding.UTF8.GetString(credentialBytes).Split(':', 2);

            if (credentials.Length != 2 || credentials[0] != "test" || credentials[1] != "test")
            {
                context.Response.StatusCode = 403;
                await context.Response.WriteAsync("Invalid username or password.");
                return;
            }

            await _next(context);
        }
    }

    public static class BasicAuthMiddlewareExtensions
    {
        public static IApplicationBuilder UseBasicAuthMiddleware(this IApplicationBuilder builder)
        {
            return builder.UseMiddleware<BasicAuthMiddleware>();
        }
    }

Apply Authentication: In program.cs :


app.UseHttpsRedirection();
app.UseAuthorization();
//Use Basic Auth Middleware
app.UseBasicAuthMiddleware();
app.MapControllers();
app.Run();

Swagger Configuration:

// Add Swagger with Basic Authentication configuration
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Payment API - Basic Auth", Version = "v1" });
    c.AddSecurityDefinition("Basic", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "basic",
        In = ParameterLocation.Header,
        Description = "Enter your username and password as Base64 encoded value in the format 'username:password'."
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Basic"
                }
            },
            new string[] { }
        }
    });
});


var app = builder.Build();

When you run your API :

Note that you should change the way how to handle the login process ( secure password etc..)

3. JWT Authentication

JWT (JSON Web Token) is a widely-used method for securing APIs. It provides a compact and self-contained token format that includes user claims and is signed for integrity.
Required Package

Install the following NuGet package:

Microsoft.AspNetCore.Authentication.JwtBearer

Implementation:

Add Authentication Controller : In this controller , we handle the way how users login and we generate tokens for them.

[ApiController]
    [Route("api/[controller]")]
    public class AuthController : ControllerBase
    {
        private readonly IConfiguration _configuration;

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

        [HttpPost("login")]
        public IActionResult Login([FromBody] LoginRequest login)
        {
            // Validate user credentials (hardcoded for example purposes)
            if (login.Username != "test" || login.Password != "test")
                return Unauthorized("Invalid username or password");

            // Generate the JWT token
            var token = GenerateJwtToken(login.Username);

            return Ok(new { Token = token });
        }

        private string GenerateJwtToken(string username)
        {
            var jwtSettings = _configuration.GetSection("Jwt");

            var claims = new[]
            {
            new Claim(JwtRegisteredClaimNames.Sub, username),
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
            new Claim(ClaimTypes.Role, "Admin")
        };

            var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwtSettings["Key"]));
            var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

            var token = new JwtSecurityToken(
                issuer: jwtSettings["Issuer"],
                audience: jwtSettings["Audience"],
                claims: claims,
                expires: DateTime.UtcNow.AddHours(1),
                signingCredentials: creds);

            return new JwtSecurityTokenHandler().WriteToken(token);
        }
    }

User model :

    public class LoginRequest
    {
        public string Username { get; set; }
        public string Password { get; set; }
    }

Add Authentication Service: In program.cs , we configure the authentication service for our application :

var builder = WebApplication.CreateBuilder(args);

var jwtSettings = builder.Configuration.GetSection("Jwt");
var key = Encoding.UTF8.GetBytes(jwtSettings["Key"]);

builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
}).AddJwtBearer(options =>
{
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = true,
        ValidateIssuerSigningKey = true,
        ValidIssuer = jwtSettings["Issuer"],
        ValidAudience = jwtSettings["Audience"],
        IssuerSigningKey = new SymmetricSecurityKey(key)
    };
});
// Add services to the container.

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();

Apply Authentication: Let's apply the authentication now in program.cs:

app.UseHttpsRedirection();
// Add Authentication
app.UseAuthentication();
app.UseAuthorization(); //<--
app.MapControllers();
app.Run();

Swagger Configuration: Let's configure our swagger so it shows the Authorize button using Jwt

// Add Swagger with JWT configuration
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Paymnent API - JWT", Version = "v1" });
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "Enter 'Bearer' [space] and then your valid token."
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] { }
        }
    });
});

var app = builder.Build();

In appsettings.json we add the necessary informations:

 "Jwt": {
    "Key": "SuperSecretKey12345SuperSecretKey12345SuperSecretKey12345SuperSecretKey12345",
    "Issuer": "SecureApiJwt",
    "Audience": "ApiUsers",
    "ExpiryMinutes": 60
  }

Don't forget to add [Authorize] in you controllers

To test now , you should Login , you will get a token . In authorize button , you should add the generated token to access to the endpoints

Conclusion

Securing your .NET API is essential to ensure the integrity and confidentiality of the data it processes. Here's a comparison of the three methods discussed:

You can find the full code in my GitHub repo
Next Article will be on how me make our API accessed from other applications throw nuget package and handling the security .

The Ultimate Guide to Unit Testing in .NET (C#) Using xUnit and Moq (Without the Boring Examples)

Zied Rebhi — Mon, 02 Dec 2024 17:51:20 +0000

Alright, developers, gather ‘round. We’ve all been there, right? You’re looking for some unit testing examples, and what do you get? A classic sum function test. Really? The sum of two numbers? It’s like someone telling you, “Hey, you should totally learn to swim by jumping in the shallow end of the kiddie pool.” Ugh, no thanks!

But fear not, because in this article, we’re taking things up a notch. You’ll get real-world examples, not just the “add two numbers” stuff. We’re talking asynchronous methods, complex CQRS workflows, API controllers, and services that interact with databases. Sounds like a party? You bet! 🎉

So, buckle up as we dive deep into xUnit, Moq, and all the other goodies that make testing in C# both powerful and fun. By the end of this guide, you’ll be writing tests for real code in no time, and they’ll actually mean something. 🚀

Why xUnit and Moq?

You know that feeling when you’re trying to mock a database call and nothing seems to work? Or when you’re trying to test a service, but its dependencies are just too messy? Yeah, that’s where xUnit and Moq come in to save the day.

xUnit: It’s like the Swiss Army knife of unit testing. Simple, easy-to-use, and powerful enough to tackle anything.
Moq: The mock framework that makes dependencies easier to deal with. No more struggling with setup methods or breaking your code into a thousand pieces just to test one thing.

So, xUnit and Moq are like peanut butter and jelly. Together, they make testing smoother and tastier. 🍞🍇

When writing unit tests, you often need to isolate the code you’re testing from external dependencies like databases, APIs, or services. Moq allows you to create these “fake” objects, or mocks, so that you can focus on testing the logic of your code without worrying about the real external systems. With Moq, you can specify how these fake objects should behave (e.g., what they should return when a method is called), and verify that the methods are called correctly during the test. This makes testing more efficient and reliable.

Setting Up xUnit and Moq (It’s Simple, I Promise)

First, let’s get these bad boys installed so we can start writing tests:

No magic here. Just a quick setup, and we’re ready to roll.

1. Basic Service Testing (No, Not a Sum Function!)

Let’s start with something real. We’ll write a UserService that fetches user data from a repository. Why? Because fetching user data is something you actually do in real apps, not just summing numbers. 😜

Service: UserService

Test for UserService

Let’s test it. Mock the repository, and then check if the GetUserByIdAsync method actually returns a user (and doesn’t just return null—we're looking for something useful here, not just empty promises).

Takeaway: This is a real test for a service that retrieves data from a database. It’s not a “sum of two numbers” function, and you actually care about testing it. 🎯

2. Testing Asynchronous Methods (The Real Deal)

Let’s talk about async/await because real applications often deal with I/O-bound operations. You know, things like making HTTP calls or reading from a database. We need to test that this works correctly.

Service: PaymentService

Here, we’ll test a service that processes payments. It calls multiple external services to check user data, order details, and payment processing.

Tests for PaymentService

Now let’s test it, making sure everything is mocked and asynchronous behavior works as expected.

Takeaway: These tests are all about real-world async calls. They help us ensure the method interacts with multiple services and handles various scenarios correctly.

3. MediatR + CQRS (Let’s Make it Fancy)

You might have heard about CQRS (Command Query Responsibility Segregation) and MediatR. If not, let me explain: CQRS is about separating your reads and writes into different models, and MediatR helps you handle them. Let’s see how this works in real life.

Command: CreateOrderCommand

Test for CreateOrderCommandHandler

We’ll test that the command handler behaves correctly and sends the OrderCreatedEvent when a new order is created.

Takeaway: This is where things get advanced. We’re testing a CQRS command handler that uses MediatR to send events and execute commands. This is the real deal for complex applications.

4. Event-Driven Architecture (Publish-Subscribe Pattern)

In many modern systems, events drive a lot of the functionality. For instance, an order creation event might trigger a series of other actions, such as sending a confirmation email, updating the inventory, or notifying a user.

Let’s build an event-driven system using MediatR and test the subscription to an event.

Event: OrderCreatedEvent

Handler: OrderCreatedEventHandler

Test for OrderCreatedEventHandler

We’ll now write a test to ensure that the email service is triggered correctly when an order is created.

Takeaway: Event-driven systems are a common architecture, especially in microservices. This test ensures that the system reacts appropriately to events, like sending emails when an order is created.

5. Background Job Processing (Hangfire)

In many applications, you need to process tasks in the background. This is often done via background job processing systems like Hangfire or Quartz.NET.

Here’s how we can test a background job that processes a payment.

Background Job: ProcessPaymentJob

Test for ProcessPaymentJob

Let’s test the background job by ensuring that it calls the ProcessPaymentAsync method from the IPaymentService.

Takeaway: Background jobs are essential for handling long-running processes. This test ensures that background tasks trigger the necessary service methods.

6. Integrating with External APIs (Third-Party Service)

In real-world apps, you often need to interact with third-party APIs. Whether it’s sending a message through Twilio, fetching weather data from an external service, or processing payments through Stripe, you’ll need to test how your system interacts with these external systems.

External Service: WeatherService

Let’s assume we have a weather service that fetches the current temperature.

Test for WeatherService

To test this, we will mock the HttpClient using Moq and make sure that the service returns the expected response.

Takeaway: Testing integration with third-party services is crucial for external dependencies. By mocking the HTTP response, we ensure that our service works without actually calling the real API (and risking running out of API calls for the day!).

6. Testing API Controllers (With Dependency Injection)

In web applications, controllers often rely on dependency injection to get their services. Let’s look at testing an API controller that uses injected services.

Controller: OrderController

Test for OrderController

We’ll now test the controller method GetOrderById. We’ll mock the IOrderService to simulate database interaction.

Takeaway: When testing API controllers, mocking the injected services ensures that you test only the controller’s behavior, without depending on real databases or external services.

Conclusion: You’re Now Ready to Tackle Any Test!

Congratulations, my friend! 🎉 You’ve now seen advanced tests, covering everything from event-driven architectures, background jobs, third-party service integrations, to API controllers. With the power of xUnit, Moq, and MediatR, you’re now able to confidently test even the most complex systems.

The next time you hear someone say, “I don’t know how to test this,” you can confidently say, “I got you!” 🙌

Remember, in the world of testing, the more real your examples are, the more prepared you’ll be. So keep practicing, keep building, and make testing your superpower! 💪

Recurring Tasks in .NET C# : All options explained

Zied Rebhi — Mon, 02 Dec 2024 17:47:50 +0000

Recurring Tasks in .NET C# : All options explained

In many applications, tasks need to be run on a regular schedule. Examples include data synchronization, email reminders, cleanup routines, and background processing. .NET provides several ways to accomplish this, from simple in-app timers to robust enterprise-level scheduling with external libraries and cloud solutions.

1. Using IHostedService for Background Services :

Starting with .NET Core, IHostedService is the preferred way to run background tasks. It’s suitable for services that need to perform periodic work within the same application, such as logging, data processing, or scheduled updates.

Key Features

Integrated with the .NET Core dependency injection (DI) container.
Runs continuously or at set intervals.
Suitable for background tasks tied closely to the lifecycle of a web app or API.

Implementation Steps

Implement a Background Service:

Implement BackgroundService (a specialized version of IHostedService) to define a recurring task.

2. Register the Background Service:

When to Use

Simple periodic tasks.
Scenarios where the recurring job needs to be integrated with the main application’s lifecycle.

2. Using System.Threading.Timer

System.Threading.Timer is another simple way to execute periodic tasks. It’s lightweight and does not depend on hosted services, so it can be used in standalone applications or other contexts outside of ASP.NET Core applications.

Key Features

Runs on a timer interval.
Ideal for straightforward, low-overhead tasks.
No dependency on ASP.NET Core hosting or dependency injection.

Implementation Steps

**Define a Timer Service: **Create a class that uses Timer to run recurring tasks.

**2. Register the Timer Service: **Add the service to ConfigureServices to ensure it starts with your application.

When to Use

Lightweight tasks with straightforward timing needs.
Tasks that don’t require complex scheduling or clustering.

3. Using Quartz.NET

Quartz.NET is a full-featured job scheduling library that supports complex schedules, persistence, and clustering, making it ideal for enterprise applications.

Key Features

Supports complex schedules (e.g., cron expressions).
Allows jobs to be stored in a database for persistence.
Provides clustering for distributed systems.

Implementation Steps

**Install Quartz.NET: **Install the Quartz package:

**2. Define a Quartz Job: **Create a class that implements IJob to define a recurring task.

**3. Configure Quartz in Startup.cs: **Configure Quartz to schedule the job with an interval, using a cron expression or a simple schedule.

When to Use

Complex scheduling needs .
High scalability and reliability requirements.
Enterprise applications with distributed job scheduling.

4. Using Hangfire

Hangfire is a popular library for background job scheduling in .NET that provides support for recurring jobs, real-time monitoring, and persistent storage.

Key Features

Built-in support for recurring jobs with a visual dashboard.
Persistent storage for jobs (SQL Server, Redis, etc.).
Supports retries and error handling.

Implementation Steps

Install Hangfire Package:

**2. Configure Hangfire in Startup.cs: **Set up Hangfire with persistent storage and background processing.

3. Define and Schedule a Recurring Job:

When to Use

Applications requiring a simple, reliable job scheduler with real-time monitoring.
Tasks that need robust error handling and retries.
Scenarios where a visual dashboard for managing jobs is beneficial.

5. Using Azure Functions with Timer Triggers

For serverless and cloud-native applications, Azure Functions can be an effective way to manage scheduled tasks.

Key Features

Serverless execution with automatic scaling.
Managed by Azure, so no additional infrastructure management is needed.
Supports cron expressions for flexible scheduling.

Implementation Steps

**Create a Timer Trigger Function in Azure Functions: **Define the function with a Timer Trigger using a cron expression.

**2. Deploy the Function to Azure: **Deploy the function to Azure and configure the interval (e.g., hourly) using cron syntax.

When to Use

Serverless environments where you don’t want to manage infrastructure.
Scenarios where task execution needs high scalability and flexibility.

6. Using Windows Task Scheduler or Cron Jobs

For standalone applications or systems not hosted in a cloud or web environment, Windows Task Scheduler (Windows) or Cron (Linux) can handle recurring tasks by executing your .NET application on a set schedule.

Key Features

Decouples scheduling from application logic.
Ideal for desktop or on-premises applications.
Flexible scheduling options.

Implementation Steps

**Create a Console Application: **Define the recurring logic in a .NET console application.

2. Schedule the Console Application:

Windows: Use Windows Task Scheduler to set up a recurring schedule.
Linux: Use Cron jobs to run the task at specific intervals.

When to Use

Decoupled scheduling for standalone or desktop applications.
Lightweight scheduling without dependencies on third-party libraries.

Conclusion

.NET offers a range of solutions for recurring tasks, from simple timers for lightweight jobs to enterprise-level schedulers like Quartz.NET and Hangfire, as well as cloud-native options like Azure Functions. Each method has unique strengths, and the choice depends on factors such as application architecture, infrastructure requirements, and task complexity. By selecting the most suitable approach, you can implement recurring tasks that are reliable, efficient, and aligned with your application’s needs.

Documenting Your .NET Web API with Swagger: The Fun Guide

Zied Rebhi — Mon, 18 Nov 2024 22:07:42 +0000

magine this: You’re the new dev on the team, and someone hands you the API code to work with. You open it up and stare at it, confused, like you’ve just found a treasure map with no X marks the spot. You’re thinking, Whaaaat is this thing even supposed to do? 🧐

Or picture this: You’re the QA tester, and you’ve been handed this mysterious API with zero documentation. Every time you try to test, you end up with more questions than answers. You find yourself emailing the dev team with questions like, What does this endpoint even return? How do I use this thing? 😵

Or, worst case scenario, you’re another team that’s supposed to use the API you’ve never seen before. You try making a call, and then… boom! You’re calling the original devs non-stop for clarification, like, Hey, how do I get a list of food items? What’s the format of the response? It’s like they’re your personal helpdesk. 📞💻

We’ve all been there, right? But fear not, because Swagger is here to save the day! 🦸‍♂️ Let’s show you how you can turn your messy, undocumented API into something that even your new teammate, your tester, and those poor souls in other teams can understand with zero hassle.

Why Document Your API?

So why should we go through all this effort? Well, imagine trying to navigate a new city without a map — that’s what it’s like trying to use an undocumented API. Documentation makes everything clearer, and it’s not just for you! It’s for your team, for testers, and for those poor souls in other teams who just want to use your API without calling you every hour. 🤳

Step 1: Set Up Swagger

First things first: let’s set up Swagger in your project. Swagger turns your API into a shiny, interactive dashboard. It’s like giving your API a GPS, a guidebook, and a snack (just to make it extra pleasant). 🗺️🍿

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Food API",
        Description = "A sample application with Swagger, Swashbuckle, and API versioning for managing Foods",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        },
        TermsOfService = new Uri("https://example.com/terms"),
    });
 // using System.Reflection;
 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
 options.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
});

Then enable XML comments by adding this to your _.csproj _file :

Right-click the project in Solution Explorer and select Edit .csproj.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Now you’re ready to start adding documentation to your API. This is where the magic happens!

Step 2: Documenting Your API with Swagger Annotations

Now let’s give your API some personality. Here’s an example of a Food API that’s fully documented. We’re going to make it clear, concise, and helpful — so no one has to call you 15 times a day asking questions. 😅

using Microsoft.AspNetCore.JsonPatch;
using Microsoft.AspNetCore.Mvc;
using Swashbuckle.AspNetCore.Annotations;

namespace FoodApi.Controllers.v3
{
    /// <summary>
    /// Manages food-related operations.
    /// </summary>
    [ApiController]
    [ApiVersion("3.0")]
    [Route("api/v{version:apiVersion}/[controller]")]
    public class FoodController : ControllerBase
    {
        /// <summary>
        /// Retrieves a list of all food items.
        /// </summary>
        /// <remarks>
        /// Example request:
        /// `http
        /// GET /api/v3.0/Food
        /// `
        /// Example response:
        /// `json
        /// [
        ///     { "id": 1, "name": "Apple", "calories": 95 },
        ///     { "id": 2, "name": "Banana", "calories": 105 }
        /// ]
        /// `
        /// </remarks>
        [HttpGet]
        [SwaggerOperation(Summary = "Get all food items", Description = "Retrieves a list of all food items.")]
        [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(IEnumerable<FoodItemDto>))]
        public ActionResult<IEnumerable<FoodItemDto>> GetAllFoods()
        {
            return Ok(new List<FoodItemDto>
        {
            new FoodItemDto { Id = 1, Name = "Apple", Calories = 95 },
            new FoodItemDto { Id = 2, Name = "Banana", Calories = 105 }
        });
        }

        /// <summary>
        /// Retrieves a specific food item by ID.
        /// </summary>
        /// <remarks>
        /// Example request:
        /// `http
        /// GET /api/v3.0/Food/1
        /// `
        /// Example response:
        /// `json
        /// { "id": 1, "name": "Apple", "calories": 95 }
        /// `
        /// </remarks>
        /// <param name="id">The unique identifier of the food item.</param>
        /// <response code="200">The food item was successfully retrieved.</response>
        /// <response code="404">The food item with the given ID was not found.</response>
        [HttpGet("{id}")]
        [SwaggerOperation(Summary = "Get a food item by ID", Description = "Retrieves a specific food item by its unique ID.")]
        [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(FoodItemDto))]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public ActionResult<FoodItemDto> GetFoodById(int id)
        {
            if (id <= 0) return NotFound();

            return Ok(new FoodItemDto { Id = id, Name = "Apple", Calories = 95 });
        }

        /// <summary>
        /// Retrieves food details (deprecated method).
        /// </summary>
        /// <remarks>
        /// **This method is obsolete. Use `GetFoodById` instead.**
        /// Example usage:
        /// `http
        /// GET /api/v3.0/Food/details/1
        /// `
        /// **Response:**
        /// `json
        /// { "id": 1, "name": "Apple", "calories": 95 }
        /// `
        /// **Error Response:**
        /// `json
        /// { "error": "Not Found" }
        /// `
        /// </remarks>
        /// <param name="id">The unique identifier of the food item.</param>
        /// <response code="200">The food item was successfully retrieved.</response>
        /// <response code="404">The food item with the given ID was not found.</response>
        [Obsolete("This method is deprecated. Use GetFoodById instead.")]
        [HttpGet("details/{id}")]
        [SwaggerOperation(Summary = "Get food details (deprecated)", Description = "Retrieves detailed food information (use `GetFoodById` instead).")]
        [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(FoodItemDto))]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public ActionResult<FoodItemDto> GetFoodDetails(int id)
        {
            if (id <= 0) return NotFound();

            return Ok(new FoodItemDto { Id = id, Name = "Apple", Calories = 95 });
        }

        /// <summary>
        /// Creates a new food item.
        /// </summary>
        /// <remarks>
        /// Example request:
        /// `json
        /// { "name": "Apple", "calories": 95 }
        /// `
        /// Example response:
        /// `json
        /// { "id": 123, "name": "Apple", "calories": 95 }
        /// `
        /// </remarks>
        /// <param name="foodItem">The food item to create.</param>
        /// <response code="201">The food item was successfully created.</response>
        /// <response code="400">Invalid food item details.</response>
        [HttpPost]
        [SwaggerOperation(Summary = "Create a new food item", Description = "Creates a new food item in the system.")]
        [ProducesResponseType(StatusCodes.Status201Created, Type = typeof(FoodItemDto))]
        [ProducesResponseType(StatusCodes.Status400BadRequest)]
        public ActionResult<FoodItemDto> CreateFood(FoodItemDto foodItem)
        {
            if (string.IsNullOrEmpty(foodItem.Name) || foodItem.Calories <= 0)
            {
                return BadRequest("Invalid food item details.");
            }

            foodItem.Id = new Random().Next(1, 1000); // Simulate ID generation
            return CreatedAtAction(nameof(GetFoodById), new { id = foodItem.Id }, foodItem);
        }

        /// <summary>
        /// Updates an existing food item.
        /// </summary>
        /// <remarks>
        /// Example request:
        /// `json
        /// { "id": 1, "name": "Banana", "calories": 110 }
        /// `
        /// Example response:
        /// `json
        /// { "id": 1, "name": "Banana", "calories": 110 }
        /// `
        /// </remarks>
        /// <param name="id">The unique identifier of the food item to update.</param>
        /// <param name="foodItem">The updated food item data.</param>
        /// <response code="200">The food item was successfully updated.</response>
        /// <response code="400">Food item ID mismatch or invalid data.</response>
        /// <response code="404">The food item with the given ID was not found.</response>
        [HttpPut("{id}")]
        [SwaggerOperation(Summary = "Update an existing food item", Description = "Updates a specific food item.")]
        [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(FoodItemDto))]
        [ProducesResponseType(StatusCodes.Status400BadRequest)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public ActionResult<FoodItemDto> UpdateFood(int id, FoodItemDto foodItem)
        {
            if (id != foodItem.Id) return BadRequest("Food item ID mismatch.");
            if (id <= 0) return NotFound();

            return Ok(foodItem); // Return the updated food item
        }

        /// <summary>
        /// Deletes a food item by ID.
        /// </summary>
        /// <remarks>
        /// Example request:
        /// `http
        /// DELETE /api/v3.0/Food/1
        /// `
        /// Example response:
        /// `json
        /// { "message": "Food item deleted successfully." }
        /// `
        /// </remarks>
        /// <param name="id">The unique identifier of the food item to delete.</param>
        /// <response code="200">The food item was successfully deleted.</response>
        /// <response code="404">The food item with the given ID was not found.</response>
        [HttpDelete("{id}")]
        [SwaggerOperation(Summary = "Delete a food item", Description = "Deletes a specific food item.")]
        [ProducesResponseType(StatusCodes.Status200OK)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public IActionResult DeleteFood(int id)
        {
            if (id <= 0) return NotFound();

            return Ok(new { Message = "Food item deleted successfully." });
        }

        /// <summary>
        /// Partially updates a food item (e.g., updating only calories).
        /// </summary>
        /// <remarks>
        /// Example request:
        /// `json
        /// { "calories": 110 }
        /// `
        /// Example response:
        /// `json
        /// { "id": 1, "name": "Apple", "calories": 110 }
        /// `
        /// </remarks>
        /// <param name="id">The unique identifier of the food item to update.</param>
        /// <param name="patchDoc">The JSON patch document containing the changes to apply.</param>
        /// <response code="200">The food item was successfully updated.</response>
        /// <response code="400">Invalid patch data.</response>
        /// <response code="404">The food item with the given ID was not found.</response>
        [HttpPatch("{id}")]
        [SwaggerOperation(Summary = "Partially update a food item", Description = "Partially updates an existing food item.")]
        [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(FoodItemDto))]
        [ProducesResponseType(StatusCodes.Status400BadRequest)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public ActionResult<FoodItemDto> PatchFood(int id, [FromBody] JsonPatchDocument<FoodItemDto> patchDoc)
        {
            if (id <= 0) return NotFound();
            if (patchDoc == null) return BadRequest("Invalid patch data.");

            var foodItem = new FoodItemDto { Id = id, Name = "Apple", Calories = 95 };

            patchDoc.ApplyTo(foodItem, ModelState);

            if (!ModelState.IsValid) return BadRequest(ModelState);

            return Ok(foodItem);
        }
    }

    /// <summary>
    /// Represents a food item.
    /// </summary>
    public class FoodItemDto
    {
        /// <summary>
        /// Unique identifier of the food item.
        /// </summary>
        /// <example>1</example>
        public int Id { get; set; }

        /// <summary>
        /// The name of the food item.
        /// </summary>
        /// <example>Apple</example>
        public string Name { get; set; }

        /// <summary>
        /// The number of calories in the food item.
        /// </summary>
        /// <example>95</example>
        public int Calories { get; set; }
    }
}

What Have We Done?

Let’s break down exactly what’s happening here. Here’s why this documentation is a game-changer:

1.Added Summaries:
Each method now has a /// tag, which is like giving your API a clear job description. For example, Retrieves a list of all food items is super helpful for anyone trying to understand what this endpoint does.

2. Clear Remarks:
We included /// to show exactly what’s expected when making requests and receiving responses. Now testers can see the request format, and other devs won’t be left in the dark wondering what a valid response looks like.

3. Error Handling:
We documented potential error responses with /// , which means if something goes wrong, your API will tell the user exactly what happened. No more guessing, no more surprises! (Remember, the only surprise should be when the food's really good. 😜)

4. Obsolete Methods:
We used the [Obsolete] attribute to let users know that old methods are no longer the way to go. This is a life-saver when the next dev or team calls you up and says, “Wait, should we use this?” Answer: “Nope, use the new one!” ✅

5. Response Types:
With the [ProducesResponseType] attribute, we made sure Swagger knows what kind of responses your API sends back. So now, your users (and that other dev team calling you) can easily see that a 200 OK means success, or 404 Not Found means they might want to double-check their inputs.

6. Parameter Descriptions:
We used /// to describe the parameters. Now, there’s no more “Wait, what does this ID mean?” Everyone knows exactly what each parameter represents. It’s like providing a map for your API. 🗺️

7. Add more descriptions to our objects / DTOs :

    /// <summary>
    /// The name of the food item.
    /// </summary>
    /// <example>Apple</example>
    public string Name { get; set; }

And That’s It!

Now your API is fully documented, and everyone (even the new devs, testers, and other teams) will love using it. No more confusing, undocumented endpoints. No more “Hey, how do I use this thing?” phone calls. Swagger makes your API transparent, easy to understand, and interactive. 🎉

So, to recap:

No more confusion for the new devs.
No more endless questions from testers.
No more panic calls from other teams wondering how to use your API.

Your API is now a smooth, well-documented experience for everyone involved. 🚀

Azure Functions in .NET (C#) — The Ultimate Fun Version 🥳

Zied Rebhi — Thu, 14 Nov 2024 19:42:37 +0000

What is Azure Functions?

Imagine you’re throwing a party. You have tons of guests (events) arriving at different times. Instead of hiring a full-time butler (server) to manage it all, you have Azure Functions, which is like a party planner who only shows up when needed. When a guest arrives (an event happens), the planner (your function) gets to work, does their thing, and leaves when the job is done. No hassle, no drama. Just pure serverless fun! 🥳

Why Should You Care About Azure Functions?

Zero Server Drama: No need to manage servers. It just works.
Scalable Like a Superhero: It grows or shrinks as needed (no stress about overworking it).
Pay Only for What You Use: You don’t pay for a full-time worker (server); you only pay for when your party planner shows up.

Setting Up Your First Azure Function

Install Your Tools: Visual Studio or Visual Studio Code is your playground. Make sure to install the Azure Functions Tools. It’s like installing your party setup kit.
Create a New Project: Open Visual Studio and create a new Azure Function project. Choose the HTTP Trigger template (because, hey, you want to start with something easy like handling guest RSVPs via HTTP, right?).

Writing Your First Function (The HTTP Trigger)

Here’s where the magic happens. Imagine this function is like sending an invite that says “Hey, tell me your name!”

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

public static class MyFirstFunction
{
    [FunctionName("HelloFunction")]
    public static async Task<IActionResult> Run(
        [HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequest req,
        ILogger log)
    {
        log.LogInformation("The function just got a request!");

        string name = req.Query["name"];

        // If they don't tell you their name, give them a little nudge
        return name != null
            ? (ActionResult)new OkObjectResult($"Hello, {name}, welcome to the party!")
            : new BadRequestObjectResult("Oops! Please tell us your name on the query string.");
    }
}

This function is triggered by an HTTP request. If someone says their name (via the query string name), the function greets them like a true host. If not, they get a “Please tell us your name!” nudge.

Testing It Out Locally:

Press F5 and your party planner (Azure Function) will run on your local machine.
Open up your browser and go to http://localhost:7071/api/HelloFunction?name=John. Your function should greet you: "Hello, John, welcome to the party!"

Example 2: Timer Trigger (The Office Alarm)

Now, let’s add a fun twist! Imagine you want to send out an announcement every 5 minutes: “Time for snacks!”

Here’s how to set up a Timer Trigger:

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using System;

public static class SnackBreak
{
    [FunctionName("SnackTimeReminder")]
    public static void Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
    {
        log.LogInformation($"It's snack time! The time is: {DateTime.Now}");
    }
}

The Timer Trigger runs every 5 minutes. You can think of it as the office alarm that reminds you to take a break. No more forgetting about snacks!

Example 3: Blob Trigger (Snack Delivery)

What if someone drops a snack (a file) into the Azure Blob Storage, and you want your function to grab it and send an alert? Here’s how:

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;

public static class BlobTriggerFunction
{
    [FunctionName("BlobSnackArrival")]
    public static void Run([BlobTrigger("snack-container/{name}", Connection = "AzureWebJobsStorage")] string myBlob, string name, ILogger log)
    {
        log.LogInformation($"New snack dropped in the container! {name} arrived. It contains: {myBlob}");
    }
}

This function gets triggered when a new snack (file) is uploaded to the snack-container. Your function immediately tells everyone, “A new snack just arrived!” 🥳

Example 4: Queue Trigger (Serving Requests)

Sometimes, you might get too many requests at once, so you need a queue. This example shows how you can use a Queue Trigger to process snack requests:

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;

public static class QueueTriggerFunction
{
    [FunctionName("ProcessSnackRequest")]
    public static void Run([QueueTrigger("snack-requests")] string snackRequest, ILogger log)
    {
        log.LogInformation($"Processing snack request: {snackRequest}");
    }
}

The function gets triggered whenever a message is added to the snack-requests queue. Imagine a request like “Bring me chips!” 🎉

Example 5: Send an Email (The Party Invite)

Let’s say you want your function to send an email whenever a new user registers for your party (or app, or whatever your event is). You can use a Queue Trigger or HTTP Trigger to handle this.

Here’s a simple example using the **SendGrid **email service to send an email.

Install SendGrid NuGet Package: First, install the SendGrid NuGet package via NuGet Package Manager or by running this in your terminal:
dotnet add package SendGrid
Create the Azure Function to Send an Email:

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using SendGrid;
using SendGrid.Helpers.Mail;
using System.Threading.Tasks;

public static class EmailTriggerFunction
{
    [FunctionName("SendWelcomeEmail")]
    public static async Task Run([QueueTrigger("new-user-queue")] string username, ILogger log)
    {
        log.LogInformation($"New user {username} registered. Sending welcome email...");

        // SendGrid API key (store it in Application Settings)
        string sendGridApiKey = Environment.GetEnvironmentVariable("SendGridApiKey");
        var client = new SendGridClient(sendGridApiKey);
        var from = new EmailAddress("partyplanner@example.com", "Party Planner");
        var subject = "Welcome to the Party!";
        var to = new EmailAddress($"{username}@example.com");
        var plainTextContent = "Hi, welcome to our awesome party!";
        var htmlContent = "<strong>Hi, welcome to our awesome party!</strong>";
        var msg = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);

        // Send the email
        var response = await client.SendEmailAsync(msg);
        log.LogInformation($"Email sent to {username}: {response.StatusCode}");
    }
}

How it works: This function triggers when a new user is added to the new-user-queue. It sends them a welcome email using SendGrid.
Real use case: You could use this for sending onboarding emails to new users or subscribers.

Example 6: Process Files in Blob Storage (The Snack Delivery)

Imagine you’re hosting a party and guests are dropping off snack recipes (files) in your Azure Blob Storage. You want to process those recipes and log them in the event that someone needs to order the ingredients.

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;

public static class ProcessSnackFiles
{
    [FunctionName("ProcessRecipeFile")]
    public static void Run([BlobTrigger("snacks/{name}", Connection = "AzureWebJobsStorage")] string recipeFile, string name, ILogger log)
    {
        log.LogInformation($"New recipe file: {name}. Here’s the content: {recipeFile}");

        // Process the file, for example, save it to a database or parse it
    }
}

How it works: This function listens to a blob container (snacks/). When a new file is uploaded (for example, a recipe), it triggers and logs the file contents.
Real use case: You could use this for handling uploaded documents, images, or reports.

Example 8: Durable Functions (The Party Workflow)

What if you have a complex workflow? Maybe you need to send multiple emails, update databases, and even call external APIs as part of a longer-running process (like processing party RSVPs). You can use Durable Functions to chain tasks together and ensure everything runs in order.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using System.Threading.Tasks;

public static class PartyWorkflow
{
    [FunctionName("PartyWorkflow_HttpStart")]
    public static async Task<HttpResponseMessage> Start(
        [HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestMessage req,
        [DurableClient] IDurableOrchestrationClient starter,
        ILogger log)
    {
        string instanceId = await starter.StartNewAsync("PartyWorkflow", null);
        log.LogInformation($"Started orchestration with ID = {instanceId}");

        return starter.CreateCheckStatusResponse(req, instanceId);
    }

    [FunctionName("PartyWorkflow")]
    public static async Task RunOrchestrator(
        [OrchestrationTrigger] IDurableOrchestrationContext context)
    {
        var outputs = new List<string>();

        // Call external functions or activities sequentially
        outputs.Add(await context.CallActivityAsync<string>("SendInvite", "John"));
        outputs.Add(await context.CallActivityAsync<string>("SendSnackReminder", "John"));
        outputs.Add(await context.CallActivityAsync<string>("ConfirmRSVP", "John"));

        // Do something with the outputs (like update a database or send a final email)
    }

    [FunctionName("SendInvite")]
    public static string SendInvite([ActivityTrigger] string name, ILogger log)
    {
        log.LogInformation($"Sending invite to {name}.");
        return $"Invite sent to {name}.";
    }

    [FunctionName("SendSnackReminder")]
    public static string SendSnackReminder([ActivityTrigger] string name, ILogger log)
    {
        log.LogInformation($"Sending snack reminder to {name}.");
        return $"Snack reminder sent to {name}.";
    }

    [FunctionName("ConfirmRSVP")]
    public static string ConfirmRSVP([ActivityTrigger] string name, ILogger log)
    {
        log.LogInformation($"Confirming RSVP for {name}.");
        return $"RSVP confirmed for {name}.";
    }
}

How it works: This example demonstrates Durable Functions, where multiple activities (like sending an invite, reminding guests about snacks, and confirming RSVPs) are orchestrated together. This is great for workflows that need to maintain state or wait for external inputs.
Real use case: Perfect for processing complex tasks like order processing, multi-step approvals, or handling multi-step customer interactions.

Example 9: Integrating with External APIs (The Party Food Order)

What if you need to order food or supplies from an external service (like an API)? Here’s how you can integrate Azure Functions with an external API to automate ordering party supplies!

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using System.Net.Http;
using System.Threading.Tasks;

public static class ExternalApiTrigger
{
    private static readonly HttpClient client = new HttpClient();

    [FunctionName("OrderFood")]
    public static async Task Run([TimerTrigger("0 0 12 * * *")] TimerInfo myTimer, ILogger log)
    {
        log.LogInformation("Time to order food!");

        // Make an API call to an external service to order food
        HttpResponseMessage response = await client.GetAsync("https://api.foodservice.com/order?item=pizza");

        if (response.IsSuccessStatusCode)
        {
            log.LogInformation("Food order placed successfully!");
        }
        else
        {
            log.LogError("Failed to place food order.");
        }
    }
}

How it works: This function is triggered daily at noon (with a Timer Trigger). It calls an external API to order pizza for the party (or other supplies).
Real use case: You could use this in an e-commerce setting or any business that needs to interact with external APIs on a schedule.

Cost Management: Pay Only for What You Eat (Or Use)

The best part? You only pay when your function is doing its job, like a party planner that only bills you for the time they actually worked! There are several pricing plans:

Consumption Plan: Pay for only the time your function runs.
Premium Plan: More control, more features (like VNET integration).
Dedicated Plan: Full-time party planner with fixed scaling.

Conclusion: More Ways to Party with Azure Functions

With these real examples, you can see how Azure Functions can be used for a variety of tasks — from sending emails, processing files, and interacting with external APIs, to managing complex workflows with Durable Functions.

The best part? Azure Functions is like the best party planner: it shows up when needed, gets the job done, and leaves without any fuss. Plus, it scales automatically, so no party is too big or too small! 🥳