Decode.AspNetCore 2.0.0

Decode.AspNetCore

ASP.NET Core extensions for the Decode ecosystem, providing standardized infrastructure for APIs, including OpenAPI 3.0 Swagger configuration, User Context resolution, global exception handling, and base controllers integrated with Domain Notifications.

🚀 Features

• Swagger / OpenAPI 3.0 Integration: 1-line setup (AddDecodeSwagger) with OpenAPI 3.0 HTTP Bearer authentication, environment security guard (UseDecodeSwagger), auto-discovery of XML documentation files, and native Swashbuckle escape hatches.
• IUserContext & UserContext: Web API implementation of IUserContext using IHttpContextAccessor, safely resolving UserId, client IP address, User-Agent, Bearer access token, and custom claims.
• GlobalExceptionMiddleware: A robust safety net that captures unhandled exceptions, logs them with a unique errorId, and returns a standardized JSON response.
• ApiControllerBase: A base controller that simplifies response handling by automatically checking for domain notifications and returning appropriate HTTP status codes.
• ApiResponse: A unified response model for all API endpoints: { success, data, errors, errorId }.

📦 Installation

Add the project reference to your API:

dotnet add reference ../Decode.AspNetCore/Decode.AspNetCore.csproj

🛠️ Setup

1. Register Services in Program.cs

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// 1. Add Decode ASP.NET Core infrastructure (Domain Notifications + IUserContext)
builder.Services.AddDecodeAspNetCore();

// 2. Add Decode Swagger/OpenAPI 3.0
builder.Services.AddDecodeSwagger(options =>
{
    options.Title = "My Enterprise API";
    options.Version = "v1";
    options.Description = "Authentication and Core API endpoints.";
    options.EnableJwtBearer = true;      // Enables native HTTP Bearer lock icon
    options.IncludeXmlComments = true;   // Auto-discovers all *.xml docs in execution folder
});

2. Configure HTTP Pipeline

WebApplication app = builder.Build();

// 1. Add global exception middleware at top of pipeline
app.UseGlobalExceptionMiddleware();

// 2. Enable Swagger UI (auto-disabled in Production unless forced)
app.UseDecodeSwagger();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();
app.Run();

📖 Usage Examples

1. Using ApiControllerBase with Notifications

Inherit from ApiControllerBase to get automatic notification handling:

using Decode.AspNetCore.Controllers;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ApiControllerBase
{
    private readonly IProductService _service;

    public ProductsController(IProductService service)
    {
        _service = service;
    }

    [HttpPost]
    public IActionResult Create(Product product)
    {
        _service.Create(product);

        // If _service added notifications to IDomainNotificationContext,
        // CreatedResponse() will automatically return 400 Bad Request (or custom status code).
        // Otherwise, it returns 201 Created.
        return CreatedResponse($"/api/products/{product.Id}", product);
    }
}

2. Using IUserContext in Controllers or Services

using Decode.Context.Abstractions;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class ProfileController(IUserContext userContext) : ControllerBase
{
    [HttpGet]
    public IActionResult GetMyProfile()
    {
        Guid currentUserId = userContext.UserId;
        string clientIp = userContext.IpAddress;

        return Ok(new
        {
            UserId = currentUserId,
            Ip = clientIp,
            IsAuthenticated = userContext.IsAuthenticated
        });
    }
}

Client IP address and proxies (changed in 2.0.0)

IpAddress returns Connection.RemoteIpAddress and does not read X-Forwarded-For by default.

Any client can set that header on its own request, so trusting it unconditionally — as versions before 2.0.0 did — let a caller choose the address recorded in audit logs, rate limiters and abuse heuristics.

The recommended setup is ASP.NET Core's own ForwardedHeadersMiddleware, which validates against a configured list of known proxies and rewrites RemoteIpAddress before UserContext ever reads it:

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    options.KnownProxies.Add(IPAddress.Parse("10.0.0.1"));
});

app.UseForwardedHeaders();

If you must read the header directly, opt in explicitly — only when the application sits behind a proxy you control that overwrites it:

builder.Services.AddDecodeAspNetCore(options => options.TrustForwardedHeaders = true);

IPv6 addresses are also preserved as-is. Earlier versions applied MapToIPv4() to every remote address, which reinterprets the last four bytes of a genuine IPv6 address: 2001:db8::1 was reported as 0.0.0.1. Only IPv4-mapped addresses (::ffff:203.0.113.10) are unwrapped now.

Standard Response Format

Success (200 OK / 201 Created):

{
  "success": true,
  "data": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Product A" },
  "errors": null,
  "errorId": null
}

Domain Notification Error (400 Bad Request):

{
  "success": false,
  "data": null,
  "errors": ["Product name is required"],
  "errorId": null
}

Unhandled Error (500 Internal Server Error):

{
  "success": false,
  "data": null,
  "errors": ["An internal server error occurred. Please try again later."],
  "errorId": "0HMA1B2C3D4E5:00000001"
}

📄 License

This project is licensed under the MIT License.