A comprehensive ASP.NET Core response wrapper that transforms your APIs into enterprise-grade endpoints with zero code changes. Automatically wraps controller responses in a consistent format with rich metadata including execution timing, correlation IDs, request tracking, and comprehensive error handling. Features intelligent application status code extraction and promotion for complex workflow management, automatic pagination metadata separation using duck typing (works with ANY pagination library), database query statistics integration, and extensive configuration options. Includes built-in exception types for common scenarios (ValidationException, NotFoundException, BusinessException, etc.), customizable error messages for localization, global exception handling middleware, and smart exclusion capabilities for specific endpoints or result types. Perfect for microservices, complex business workflows, and APIs requiring consistent client-side error handling. Supports .NET 9.0+ with minimal performance overhead and extensive debugging capabilities.
Automatic API response wrapping with metadata injection for ASP.NET Core applications.
FS.AspNetCore.ResponseWrapper provides a consistent, standardized response format for your ASP.NET Core APIs with zero boilerplate code. Transform your raw controller responses into rich, metadata-enhanced API responses that include execution timing, pagination details, correlation IDs, and comprehensive error handling.
🎯 Why ResponseWrapper?
Building robust APIs means handling consistent response formats, error management, timing information, and pagination metadata. Without a standardized approach, you end up with:
Inconsistent Response Formats: Different endpoints returning data in different structures
Manual Error Handling: Writing repetitive error response logic in every controller
Missing Metadata: No execution timing, correlation IDs, or request tracking
Complex Pagination: Mixing business data with pagination information
Debugging Difficulties: Limited insight into request processing and performance
ResponseWrapper solves all these challenges by automatically wrapping your API responses with a consistent structure, comprehensive metadata, and intelligent error handling.
✨ Key Features
🔄 Automatic Response Wrapping
Transform any controller response into a standardized format without changing your existing code.
⏱️ Performance Monitoring
Built-in execution time tracking and database query statistics for performance optimization.
🔍 Request Tracing
Automatic correlation ID generation and tracking for distributed systems debugging.
📄 Smart Pagination
Automatic detection and clean separation of pagination metadata from business data using duck typing.
🚨 Comprehensive Error Handling
Global exception handling with customizable error messages and consistent error response format.
🎛️ Flexible Configuration
Extensive configuration options for customizing behavior, excluding specific endpoints, and controlling metadata generation.
🦆 Duck Typing Support
Works with ANY pagination implementation - no need to change existing pagination interfaces.
ResponseWrapper provides extensive configuration options to customize behavior according to your needs.
Basic Configuration
builder.Services.AddResponseWrapper(options =>
{
// Enable/disable execution time tracking
options.EnableExecutionTimeTracking = true;
// Enable/disable pagination metadata extraction
options.EnablePaginationMetadata = true;
// Enable/disable correlation ID tracking
options.EnableCorrelationId = true;
// Enable/disable database query statistics (requires EF interceptors)
options.EnableQueryStatistics = false;
// Control which responses to wrap
options.WrapSuccessResponses = true;
options.WrapErrorResponses = true;
// Exclude specific paths from wrapping
options.ExcludedPaths = new[] { "/health", "/metrics", "/swagger" };
// Exclude specific result types from wrapping
options.ExcludedTypes = new[] { typeof(FileResult), typeof(RedirectResult) };
});
Advanced Configuration with Custom Error Messages
builder.Services.AddResponseWrapper(
options =>
{
options.EnableExecutionTimeTracking = true;
options.EnableQueryStatistics = true;
options.ExcludedPaths = new[] { "/health", "/metrics" };
},
errorMessages =>
{
errorMessages.ValidationErrorMessage = "Please check your input and try again";
errorMessages.NotFoundErrorMessage = "The requested item could not be found";
errorMessages.UnauthorizedAccessMessage = "Please log in to access this resource";
errorMessages.ForbiddenAccessMessage = "You don't have permission to access this resource";
errorMessages.BusinessRuleViolationMessage = "This operation violates business rules";
errorMessages.ApplicationErrorMessage = "We're experiencing technical difficulties";
errorMessages.UnexpectedErrorMessage = "An unexpected error occurred. Our team has been notified";
});
Expert Configuration with Custom Dependencies
builder.Services.AddResponseWrapper<CustomApiLogger>(
dateTimeProvider: () => DateTime.UtcNow, // Custom time provider for testing
configureOptions: options =>
{
options.EnableExecutionTimeTracking = true;
options.EnableQueryStatistics = true;
},
configureErrorMessages: errorMessages =>
{
errorMessages.ValidationErrorMessage = "Custom validation message";
errorMessages.NotFoundErrorMessage = "Custom not found message";
});
🚨 Error Handling
ResponseWrapper provides comprehensive error handling that transforms exceptions into consistent API responses.
Built-in Exception Types
ResponseWrapper includes several exception types for common scenarios:
// For validation errors
throw new ValidationException(validationFailures);
// For missing resources
throw new NotFoundException("User", userId);
// For business rule violations
throw new BusinessException("Insufficient inventory for this order");
// For authorization failures
throw new ForbiddenAccessException("Access denied to this resource");
Exception Response Examples
Validation Error Response:
{
"success": false,
"data": null,
"message": "Please check your input and try again",
"errors": [
"Email is required",
"Password must be at least 8 characters"
],
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2024-01-15T10:30:45.123Z",
"executionTimeMs": 15,
"path": "/api/users",
"method": "POST"
}
}
Not Found Error Response:
{
"success": false,
"data": null,
"message": "The requested item could not be found",
"errors": ["User (123) was not found."],
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440001",
"timestamp": "2024-01-15T10:32:15.456Z",
"executionTimeMs": 8,
"path": "/api/users/123",
"method": "GET"
}
}
Custom Error Messages
Customize error messages for different environments or languages:
// English messages
errorMessages.ValidationErrorMessage = "Please check your input and try again";
errorMessages.NotFoundErrorMessage = "The requested item could not be found";
// Turkish messages
errorMessages.ValidationErrorMessage = "Lütfen girdiğiniz bilgileri kontrol edin";
errorMessages.NotFoundErrorMessage = "Aradığınız öğe bulunamadı";
// Developer-friendly messages for development environment
if (environment.IsDevelopment())
{
errorMessages.ValidationErrorMessage = "Validation failed - check detailed errors";
errorMessages.ApplicationErrorMessage = "Application error - check logs for stack trace";
}
📄 Pagination Support
One of ResponseWrapper's most powerful features is its intelligent pagination handling using duck typing.
The Problem with Traditional Pagination
Most pagination libraries mix business data with pagination metadata:
ResponseWrapper uses duck typing, which means it works with ANY pagination implementation that has the required properties. You don't need to change your existing code!
Works with your existing pagination classes:
// Your existing pagination class - no changes needed!
public class MyCustomPagedResult<T>
{
public List<T> Items { get; set; }
public int Page { get; set; }
public int PageSize { get; set; }
public int TotalPages { get; set; }
public int TotalItems { get; set; }
public bool HasNextPage { get; set; }
public bool HasPreviousPage { get; set; }
}
// Your controller - no changes needed!
[HttpGet]
public async Task<MyCustomPagedResult<Product>> GetProducts()
{
return await _productService.GetPagedProductsAsync();
}
Also works with third-party libraries:
// Works with EntityFramework extensions
public async Task<PagedList<User>> GetUsers()
{
return await context.Users.ToPagedListAsync(page, pageSize);
}
// Works with any library that follows the pagination pattern
public async Task<PaginatedResult<Order>> GetOrders()
{
return await _orderService.GetPaginatedOrdersAsync();
}
Supported Pagination Patterns
ResponseWrapper automatically detects any object with these properties:
// Good: Specific exception types
if (user == null)
throw new NotFoundException("User", id);
if (!user.IsActive)
throw new BusinessException("User account is not active");
if (!User.IsInRole("Admin"))
throw new ForbiddenAccessException("Administrator access required");
// Avoid: Generic exceptions
// throw new Exception("Something went wrong");
3. Leverage Custom Error Messages
// Customize messages for better UX
errorMessages.ValidationErrorMessage = "Please review the highlighted fields and try again";
errorMessages.NotFoundErrorMessage = "We couldn't find what you're looking for";
errorMessages.UnauthorizedAccessMessage = "Please sign in to continue";
// Enable detailed monitoring in development
options.EnableQueryStatistics = Environment.IsDevelopment();
// Log execution times for performance monitoring
if (options.EnableExecutionTimeTracking)
{
// Monitor slow requests
if (executionTimeMs > 1000)
{
logger.LogWarning("Slow request detected: {RequestId} took {ExecutionTime}ms",
requestId, executionTimeMs);
}
}
🐛 Troubleshooting
Common Issues and Solutions
1. Responses Not Being Wrapped
Problem: Some controller responses are not wrapped.
Solutions:
Ensure controllers have the [ApiController] attribute
Check that the endpoint is not in ExcludedPaths
Verify the result type is not in ExcludedTypes
Make sure WrapSuccessResponses is enabled
[ApiController] // Required for automatic wrapping
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
// This will be wrapped
[HttpGet]
public async Task<List<User>> GetUsers() { ... }
}
2. Pagination Not Detected
Problem: Pagination metadata is not extracted from custom pagination classes.
Solution: Ensure your pagination class has all required properties:
public class MyPagedResult<T>
{
// All these properties are required
public List<T> Items { get; set; } // Required
public int Page { get; set; } // Required
public int PageSize { get; set; } // Required
public int TotalPages { get; set; } // Required
public int TotalItems { get; set; } // Required
public bool HasNextPage { get; set; } // Required
public bool HasPreviousPage { get; set; } // Required
}
3. Error Messages Not Showing
Problem: Custom error messages are not displayed.
Solutions:
Ensure GlobalExceptionHandlingMiddleware is registered
Add the middleware early in the pipeline
Check that WrapErrorResponses is enabled
var app = builder.Build();
// Add this EARLY in the pipeline
app.UseMiddleware<GlobalExceptionHandlingMiddleware>();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
4. Performance Issues
Problem: API responses are slower after adding ResponseWrapper.
Solutions:
Disable query statistics if not needed: options.EnableQueryStatistics = false
Disable execution time tracking for production: options.EnableExecutionTimeTracking = false
5. File Downloads Being Wrapped
Problem: File download endpoints are returning JSON instead of files.
Solutions:
Use ISpecialResult interface for custom file results
Add file result types to ExcludedTypes
Use the [SkipApiResponseWrapper] attribute
// Option 1: Use ISpecialResult
public class FileDownloadResult : ActionResult, ISpecialResult { ... }
// Option 2: Exclude file types
options.ExcludedTypes = new[] { typeof(FileResult), typeof(FileStreamResult) };
// Option 3: Skip specific endpoints
[SkipApiResponseWrapper("File download endpoint")]
public async Task<IActionResult> DownloadFile(int id) { ... }
🤝 Contributing
We welcome contributions to FS.AspNetCore.ResponseWrapper! Here's how you can help:
Reporting Issues
Check existing issues to avoid duplicates
Provide detailed reproduction steps
Include relevant code examples
Specify your .NET and ASP.NET Core versions
Submitting Pull Requests
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Ensure all tests pass
Update documentation if needed
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
Development Setup
# Clone the repository
git clone https://github.com/furkansarikaya/FS.AspNetCore.ResponseWrapper.git
# Navigate to the project directory
cd FS.AspNetCore.ResponseWrapper
# Restore dependencies
dotnet restore
# Build the project
dotnet build
# Run tests
dotnet test
Coding Standards
Follow Microsoft's C# coding conventions
Add comprehensive XML documentation for public APIs
Write unit tests for new features
Ensure backward compatibility when possible
📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
Microsoft for the excellent ASP.NET Core framework
The open-source community for inspiration and feedback
All contributors who help make this project better
