{"id":29195921,"url":"https://github.com/furkansarikaya/fs.aspnetcore.responsewrapper","last_synced_at":"2026-01-20T16:43:29.046Z","repository":{"id":301164005,"uuid":"1008355350","full_name":"furkansarikaya/FS.AspNetCore.ResponseWrapper","owner":"furkansarikaya","description":"🚀 Automatic API response wrapping with metadata injection for ASP.NET Core. Zero-boilerplate solution for consistent response formats, execution timing, pagination handling, and comprehensive error management. Transform your APIs with intelligent duck-typing pagination detection.","archived":false,"fork":false,"pushed_at":"2025-06-25T13:51:47.000Z","size":83,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-03T04:58:47.512Z","etag":null,"topics":["api-wrapper","aspnetcore","csharp","dotnet","error-handling","net9","netcore","response-wrapper","rest-api"],"latest_commit_sha":null,"homepage":"https://www.nuget.org/packages/FS.AspNetCore.ResponseWrapper","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/furkansarikaya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T12:17:53.000Z","updated_at":"2025-06-25T13:51:51.000Z","dependencies_parsed_at":"2025-06-25T13:42:36.168Z","dependency_job_id":"18a6f600-f46c-43ab-940f-e90cd9b12bda","html_url":"https://github.com/furkansarikaya/FS.AspNetCore.ResponseWrapper","commit_stats":null,"previous_names":["furkansarikaya/fs.aspnetcore.responsewrapper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/furkansarikaya/FS.AspNetCore.ResponseWrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/furkansarikaya%2FFS.AspNetCore.ResponseWrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/furkansarikaya%2FFS.AspNetCore.ResponseWrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/furkansarikaya%2FFS.AspNetCore.ResponseWrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/furkansarikaya%2FFS.AspNetCore.ResponseWrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/furkansarikaya","download_url":"https://codeload.github.com/furkansarikaya/FS.AspNetCore.ResponseWrapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/furkansarikaya%2FFS.AspNetCore.ResponseWrapper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264958623,"owners_count":23689035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","aspnetcore","csharp","dotnet","error-handling","net9","netcore","response-wrapper","rest-api"],"created_at":"2025-07-02T05:07:00.747Z","updated_at":"2026-01-20T16:43:29.032Z","avatar_url":"https://github.com/furkansarikaya.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FS.AspNetCore.ResponseWrapper\n\n[![NuGet Version](https://img.shields.io/nuget/v/FS.AspNetCore.ResponseWrapper.svg)](https://www.nuget.org/packages/FS.AspNetCore.ResponseWrapper)\n[![NuGet Downloads](https://img.shields.io/nuget/dt/FS.AspNetCore.ResponseWrapper.svg)](https://www.nuget.org/packages/FS.AspNetCore.ResponseWrapper)\n[![GitHub License](https://img.shields.io/github/license/furkansarikaya/FS.AspNetCore.ResponseWrapper)](https://github.com/furkansarikaya/FS.AspNetCore.ResponseWrapper/blob/main/LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/furkansarikaya/FS.AspNetCore.ResponseWrapper.svg)](https://github.com/furkansarikaya/FS.AspNetCore.ResponseWrapper/stargazers)\n\n**Enterprise-grade API response wrapper for ASP.NET Core - standardize your APIs with zero code changes.**\n\nTransform your raw controller responses into rich, metadata-enhanced API responses automatically. Add comprehensive error handling, request tracking, pagination support, and enterprise features without modifying existing code.\n\n## 🎯 Why Use This?\n\n**Problem**: Your API returns inconsistent response formats, lacks proper error handling, and provides no request tracking or metadata.\n\n**Solution**: Add one NuGet package and 2 lines of code - get enterprise-grade API responses automatically.\n\n```csharp\n// Before\npublic async Task\u003cUser\u003e GetUser(int id) =\u003e await _userService.GetUserAsync(id);\n\n// After (no code changes needed!)\npublic async Task\u003cUser\u003e GetUser(int id) =\u003e await _userService.GetUserAsync(id);\n```\n\n**Automatic transformation:**\n```json\n{\n  \"success\": true,\n  \"data\": { \"id\": 1, \"name\": \"John Doe\" },\n  \"metadata\": {\n    \"requestId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"timestamp\": \"2025-01-15T10:30:45.123Z\",\n    \"executionTimeMs\": 42,\n    \"path\": \"/api/users/1\",\n    \"method\": \"GET\"\n  }\n}\n```\n\n## ✨ Key Features\n\n- ✅ **Zero Code Changes** - Works with existing controllers automatically\n- 🔄 **Automatic Response Wrapping** - Consistent format for all endpoints\n- 🚨 **Global Error Handling** - 12 built-in exception types with error codes\n- ⏱️ **Performance Monitoring** - Automatic execution time tracking\n- 📄 **Universal Pagination** - Works with ANY pagination library (duck typing)\n- 🏷️ **Smart Metadata Extraction** - StatusCode, Message, and custom metadata\n- 🔍 **Request Tracing** - Correlation IDs for distributed systems\n- 🎛️ **Highly Configurable** - Control every aspect of wrapping behavior\n- 🛡️ **Production-Ready** - .NET 10.0 support, minimal overhead\n\n## 📦 Quick Start\n\n### 1. Install Package\n\n```bash\ndotnet add package FS.AspNetCore.ResponseWrapper\n```\n\n### 2. Configure (2 lines of code)\n\n```csharp\n// Program.cs\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddControllers();\nbuilder.Services.AddResponseWrapper(); // 👈 Line 1\n\nvar app = builder.Build();\n\napp.UseMiddleware\u003cGlobalExceptionHandlingMiddleware\u003e(); // 👈 Line 2 (optional but recommended)\napp.UseHttpsRedirection();\napp.UseAuthorization();\napp.MapControllers();\n\napp.Run();\n```\n\n### 3. That's It! 🎉\n\nYour existing controllers now return wrapped responses automatically:\n\n```csharp\n[ApiController]\n[Route(\"api/[controller]\")]\npublic class UsersController : ControllerBase\n{\n    [HttpGet(\"{id}\")]\n    public async Task\u003cUser\u003e GetUser(int id)\n    {\n        var user = await _userService.GetUserAsync(id);\n        if (user == null)\n            throw new NotFoundException(\"User\", id);\n        return user;\n    }\n}\n```\n\n**Success Response:**\n```json\n{\n  \"success\": true,\n  \"data\": { \"id\": 1, \"name\": \"John Doe\", \"email\": \"john@example.com\" },\n  \"metadata\": {\n    \"requestId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"timestamp\": \"2025-01-15T10:30:45.123Z\",\n    \"executionTimeMs\": 42\n  }\n}\n```\n\n**Error Response:**\n```json\n{\n  \"success\": false,\n  \"data\": null,\n  \"message\": \"The requested item could not be found\",\n  \"statusCode\": \"NOT_FOUND\",\n  \"errors\": [\"User (123) was not found.\"],\n  \"metadata\": {\n    \"requestId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"timestamp\": \"2025-01-15T10:32:15.456Z\"\n  }\n}\n```\n\n## 📚 Documentation\n\n### Core Package\n- 📖 [**Getting Started Guide**](docs/getting-started.md) - Step-by-step setup and basic usage\n- 🔧 [**Core Features**](docs/core-features.md) - Response structure, interfaces, error handling\n- 📄 [**Pagination Support**](docs/pagination.md) - Universal pagination with any library\n- ⚙️ [**Configuration Guide**](docs/configuration.md) - All configuration options explained\n- 💡 [**Examples**](docs/examples.md) - Real-world usage examples\n- 🐛 [**Troubleshooting**](docs/troubleshooting.md) - Common issues and solutions\n\n### Enterprise Extensions\n- 🚀 [**Enterprise Features Overview**](docs/enterprise/README.md) - All enterprise packages\n- 📊 [**OpenAPI Integration**](docs/enterprise/openapi.md) - Swagger, NSwag, Scalar support\n- 📈 [**OpenTelemetry \u0026 Tracing**](docs/enterprise/telemetry.md) - Distributed tracing and metrics\n- ⚡ [**Caching \u0026 Performance**](docs/enterprise/caching.md) - Memory, Redis, SQL Server caching\n- 🔒 [**Data Transformation**](docs/enterprise/transformation.md) - Masking, field selection, GDPR\n- 🎨 [**Preset Configurations**](docs/enterprise/presets.md) - Quick setup for common scenarios\n\n## 🎯 Common Use Cases\n\n### Basic API with Error Handling\n```csharp\nbuilder.Services.AddResponseWrapper();\napp.UseMiddleware\u003cGlobalExceptionHandlingMiddleware\u003e();\n```\n\n### API with Pagination\n```csharp\n// Works automatically with ANY pagination library!\n[HttpGet]\npublic async Task\u003cPagedResult\u003cProduct\u003e\u003e GetProducts(int page = 1)\n    =\u003e await _service.GetPagedAsync(page, 20);\n```\n\n### API with Custom Status Codes\n```csharp\npublic class LoginResult : IHasStatusCode, IHasMessage\n{\n    public string Token { get; set; }\n    public string StatusCode { get; set; } = \"LOGIN_SUCCESS\";\n    public string Message { get; set; } = \"Welcome back!\";\n}\n```\n\n### Enterprise API with All Features\n```csharp\n// Install meta package\ndotnet add package FS.AspNetCore.ResponseWrapper.Extensions\n\n// One-line setup\nbuilder.Services.AddResponseWrapperWithPreset(PresetType.Enterprise, \"MyAPI\");\napp.UseResponseWrapperExtensions();\n```\n\n## 🏢 Enterprise Features\n\nInstall the all-in-one enterprise package:\n\n```bash\ndotnet add package FS.AspNetCore.ResponseWrapper.Extensions\n```\n\n**Includes:**\n- 📊 **OpenAPI Integration** - Swashbuckle, NSwag, Scalar with enhanced schemas\n- 📈 **OpenTelemetry** - W3C trace context, distributed tracing, custom metrics\n- ⚡ **Caching** - Memory, Redis, SQL Server with ETag support\n- 🔒 **Transformation** - Data masking (PII protection), field selection, GDPR compliance\n- 🎨 **Presets** - 9 pre-configured setups (Minimal, Basic, Standard, Advanced, Enterprise, GDPR, Performance, Development, Production)\n\n**Quick Enterprise Setup:**\n```csharp\n// One line gets you everything\nbuilder.Services.AddResponseWrapperWithPreset(PresetType.Enterprise, \"MyAPI\");\napp.UseResponseWrapperExtensions();\n```\n\nSee [Enterprise Features Documentation](docs/enterprise/README.md) for details.\n\n## 🎛️ Configuration Example\n\n```csharp\nbuilder.Services.AddResponseWrapper(options =\u003e\n{\n    // Enable/disable features\n    options.EnableExecutionTimeTracking = true;\n    options.EnablePaginationMetadata = true;\n    options.EnableCorrelationId = true;\n\n    // Exclude specific endpoints\n    options.ExcludedPaths = new[] { \"/health\", \"/metrics\" };\n\n    // Customize error messages\n}, errorMessages =\u003e\n{\n    errorMessages.ValidationErrorMessage = \"Please check your input\";\n    errorMessages.NotFoundErrorMessage = \"Item not found\";\n});\n```\n\n## 🚨 Built-in Exception Types\n\n12 exception types with automatic error code extraction:\n\n- `ValidationException` - Input validation errors (400)\n- `NotFoundException` - Resource not found (404)\n- `BusinessException` - Business rule violations (400)\n- `ConflictException` - Resource conflicts (409)\n- `UnauthorizedException` - Authentication required (401)\n- `ForbiddenAccessException` - Authorization failed (403)\n- `BadRequestException` - Invalid requests (400)\n- `TimeoutException` - Operation timeout (408)\n- `TooManyRequestsException` - Rate limiting (429)\n- `ServiceUnavailableException` - Service down (503)\n- `CustomHttpStatusException` - Any custom status code\n- `ApplicationExceptionBase` - Base for custom exceptions\n\nAll exceptions include automatic error codes for client-side handling.\n\n## 📊 Response Structure\n\n```json\n{\n  \"success\": true,           // Operation outcome\n  \"data\": { ... },           // Your business data\n  \"message\": \"...\",          // Optional message\n  \"statusCode\": \"...\",       // Application status code\n  \"errors\": [...],           // Error messages (if any)\n  \"metadata\": {              // Request metadata\n    \"requestId\": \"...\",      // Unique request ID\n    \"timestamp\": \"...\",      // Response timestamp\n    \"executionTimeMs\": 42,   // Execution time\n    \"correlationId\": \"...\",  // Distributed tracing\n    \"path\": \"/api/users\",    // Request path\n    \"method\": \"GET\",         // HTTP method\n    \"pagination\": { ... },   // Pagination info (if applicable)\n    \"additional\": { ... }    // Custom metadata\n  }\n}\n```\n\n## 🔧 Requirements\n\n- .NET 10.0 or later\n- ASP.NET Core Web API project\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## 📞 Support \u0026 Links\n\n- **Documentation**: [GitHub Repository](https://github.com/furkansarikaya/FS.AspNetCore.ResponseWrapper)\n- **NuGet Package**: [FS.AspNetCore.ResponseWrapper](https://www.nuget.org/packages/FS.AspNetCore.ResponseWrapper)\n- **Issues**: [Report bugs or request features](https://github.com/furkansarikaya/FS.AspNetCore.ResponseWrapper/issues)\n- **Enterprise Package**: [FS.AspNetCore.ResponseWrapper.Extensions](https://www.nuget.org/packages/FS.AspNetCore.ResponseWrapper.Extensions)\n\n## 🌟 What's Next?\n\n1. ✅ Install the package\n2. 📖 Read the [Getting Started Guide](docs/getting-started.md)\n3. 💡 Check out [Examples](docs/examples.md)\n4. 🚀 Explore [Enterprise Features](docs/enterprise/README.md)\n\n---\n\n**Made with ❤️ by [Furkan Sarıkaya](https://github.com/furkansarikaya)**\n\n*Transform your ASP.NET Core APIs with enterprise-grade response wrapping. Install today and elevate your API development!*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffurkansarikaya%2Ffs.aspnetcore.responsewrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffurkansarikaya%2Ffs.aspnetcore.responsewrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffurkansarikaya%2Ffs.aspnetcore.responsewrapper/lists"}