IPG 1.0.9

IPG - .NET 8 Comprehensive Library

A production-ready .NET 8 library providing standardized implementations for logging, databases, security, notifications, storage, PDF generation, and more - helping you build ASP.NET Core applications 10x faster.

📦 Installation

dotnet add package IPG

🚀 Quick Start

// Program.cs
using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

// 🎯 One line to register everything!
builder.UseIPGStandard(new[] { Assembly.GetExecutingAssembly() });

var app = builder.Build();

// 🎯 One line to configure middleware!
app.UseIPGStandard();

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

That's it! Your app now has logging, CORS, Swagger, exception handling, and all configured services ready to use.

---

📚 Table of Contents

• Features by Category
• Quick Start Examples
• Configuration Guide
• Security Features
• Complete Documentation

---

🎯 Features by Category

📊 Database & ORM (Data/ directory)

• ✅ Entity Framework Core - MySQL & PostgreSQL with auto-retry logic
• ✅ Supabase PostgreSQL - Full EF Core support with scaffolding
• ✅ DbUp Migrations - SQL script-based migrations
• ✅ DbContext Factory - Thread-safe multi-threaded database access
• ✅ Connection Pooling - Optimized connection management
• ✅ Retry Policies - Automatic retry on transient failures

Extension Methods:

• AddMySqlContext<T>() - Register MySQL DbContext with retry
• AddPostgreSqlContext<T>() - Register PostgreSQL/Supabase DbContext with retry

Guides:

• 📖 Supabase EF Core Guide
• 📖 Database Usage Guide

---

🔐 Security (Middlewares/, Configuration)

• ✅ CORS Configuration - Cross-origin resource sharing with flexible policies
• ✅ JWT Authentication - Token-based authentication with bearer tokens
• ✅ OAuth Integration - Apple & Google OAuth support
• ✅ Request Tracing - Automatic trace ID generation for requests
• ✅ Exception Handling - Global exception handler with security-safe responses

CORS Features:

• Allow all origins (development mode)
• Whitelist specific origins (production)
• Array or comma-separated origins support
• Automatic AllowAnyMethod() and AllowAnyHeader()

Configuration:

{
  "Cors": {
    "AllowAny": false,
    "Origins": ["https://myapp.com", "https://www.myapp.com"]
  },
  "Jwt": {
    "SecretKey": "your-secret-key-32-chars-minimum",
    "ValidIssuer": "https://myapp.com",
    "ValidAudience": "https://myapp.com",
    "KeyDuration": 3600
  }
}

---

📝 Logging & Monitoring (Helpers/, Configuration)

• ✅ Serilog Integration - Structured logging with multiple sinks
• ✅ Application Insights - Azure cloud monitoring and telemetry
• ✅ Seq Integration - Local log aggregation and search
• ✅ Request Logging - Automatic HTTP request/response logging
• ✅ Trace ID Middleware - Correlate logs across services

Logging Sinks:

• Console (colored output)
• Debug (Visual Studio output)
• Seq (log server)
• Application Insights (Azure)

Configuration:

{
  "Serilog": {
    "serverUrl": "http://localhost:5341",
    "apiKey": "your-seq-api-key"
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=xxx;..."
  }
}

---

📧 Email & SMS (Services/, Options/)

• ✅ Azure Communication Services - Enterprise-grade email & SMS
• ✅ FluentEmail - Simple email sending with SMTP
• ✅ SMS Delivery Reports - Track SMS delivery status
• ✅ Email Templates - HTML email support

Services:

• IAzureCommunicationService - Azure Communication Services (Email & SMS)

Features:

• Send transactional emails
• Send SMS with delivery tracking
• Custom sender display names
• HTML email templates
• Bulk email/SMS support

Configuration:

{
  "AzureCommunication": {
    "ConnectionString": "endpoint=https://...;accesskey=...",
    "EnableEmail": true,
    "EnableSms": true,
    "SenderEmail": "noreply@yourdomain.com",
    "SenderDisplayName": "My Application",
    "SmsFromPhoneNumber": "+1234567890"
  }
}

Guide:

• 📖 Azure Communication Guide

---

☁️ Cloud Storage (Services/)

• ✅ Supabase Storage - Integrated with Supabase platform
• ✅ Google Cloud Storage - GCS file operations
• ✅ Azure Blob Storage - Azure file storage

Services:

• ISupabaseService - Supabase storage operations
• IGoogleStorageService - Google Cloud Storage
• IAzureBlobStorageService - Azure Blob Storage

Features:

• File upload/download/delete
• Public/private file access
• Signed URLs for secure access
• Batch operations
• Automatic retry logic

Configuration:

{
  "GoogleCredential": {
    "type": "service_account",
    "project_id": "your-project-id",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...",
    "client_email": "...@your-project.iam.gserviceaccount.com"
  },
  "AzureBlobStorage": {
    "ConnectionString": "DefaultEndpointsProtocol=https;...",
    "DefaultContainerName": "uploads"
  }
}

---

📄 PDF Generation (Services/) NEW in v1.0.8

• ✅ QuestPDF Integration - Modern, fluent PDF generation
• ✅ Invoice Templates - Professional invoice layouts
• ✅ Custom Documents - Create any PDF layout
• ✅ Stream/File/Bytes - Multiple export formats

Services:

• IPdfService - Basic PDF generation interface
• InvoicePdfService - Pre-built invoice template (example)

Features:

• Fluent API for layouts
• Tables with styling
• Headers and footers
• Custom fonts and colors
• Page numbering
• Multi-page documents

Usage:

// Register service
builder.Services.AddScoped<IPdfService, PdfService>();

// Set license (required!)
QuestPDF.Settings.License = LicenseType.Community;

// Generate PDF
var pdfBytes = _pdfService.GeneratePdf(invoiceData);
return File(pdfBytes, "application/pdf", "invoice.pdf");

Guide:

• 📖 QuestPDF Example

---

⚙️ Background Jobs (Configuration)

• ✅ Hangfire Integration - Background job processing
• ✅ MySQL/PostgreSQL Storage - Persistent job storage
• ✅ Dashboard UI - Web-based job monitoring
• ✅ Recurring Jobs - Cron-based scheduled tasks
• ✅ Job Retry - Automatic retry on failure

Configuration:

{
  "HangfireOptions": {
    "Enable": true,
    "DbType": "PostgreSQL",
    "ConnectionStrings": "Host=localhost;Database=hangfire;...",
    "WorkerCount": 5,
    "Username": "admin",
    "Password": "admin123"
  }
}

Dashboard: http://localhost:5000/hangfire

---

🔧 API Features (OpenApi/, Routes/)

• ✅ Swagger/OpenAPI - Auto-generated API documentation
• ✅ API Versioning - URL segment versioning (/api/v1/...)
• ✅ Standard Responses - Consistent API response format
• ✅ Custom Routes - OAuth and error handling routes
• ✅ Exception Handling - Global exception middleware

Configuration:

{
  "Swagger": {
    "Enable": true
  }
}

Swagger UI: http://localhost:5000/api/docs

---

🛠️ Utilities & Helpers (Services/, Helpers/)

• ✅ AutoMapper Integration - Object mapping
• ✅ Auto Service Registration - Convention-based DI
• ✅ JSON Serialization - CamelCase with enum support
• ✅ General Utilities - Common helper methods
• ✅ Extension Methods - Utility extensions

Services:

• IGeneralService - General utility methods

Auto Registration:

• Classes ending with Service are auto-registered as scoped
• Classes ending with Repository are auto-registered as scoped

---

🗄️ Supabase Platform (Services/)

• ✅ Database Operations - CRUD via Supabase client
• ✅ Authentication - Sign up, sign in, OAuth
• ✅ Storage - File upload/download
• ✅ Realtime - Live data subscriptions
• ✅ Row Level Security - Built-in security

Service:

• ISupabaseService - Complete Supabase integration

Configuration:

{
  "Supabase": {
    "Url": "https://your-project.supabase.co",
    "Key": "your-anon-public-key",
    "ServiceRoleKey": "your-service-role-key",
    "AutoRefreshToken": true,
    "PersistSession": true
  }
}

Guide:

• 📖 Supabase Usage Guide

---

🚀 Quick Start Examples

1. Database Query with Entity Framework

public class ProductsController : ControllerBase
{
    private readonly IDbContextFactory<MyDbContext> _dbFactory;

    public ProductsController(IDbContextFactory<MyDbContext> dbFactory)
    {
        _dbFactory = dbFactory;
    }

    [HttpGet]
    public async Task<IActionResult> GetProducts()
    {
        await using var context = await _dbFactory.CreateDbContextAsync();
        var products = await context.Products
            .Where(p => p.IsActive)
            .OrderBy(p => p.Name)
            .ToListAsync();
        return Ok(products);
    }
}

2. Supabase Database Operations

public class UsersController : ControllerBase
{
    private readonly ISupabaseService _supabase;

    [HttpGet]
    public async Task<IActionResult> GetActiveUsers()
    {
        var users = await _supabase.Table<User>()
            .Where(x => x.IsActive == true)
            .Order(x => x.CreatedAt, Ordering.Descending)
            .Get();

        return Ok(users.Models);
    }

    [HttpPost]
    public async Task<IActionResult> CreateUser([FromBody] User user)
    {
        await _supabase.Table<User>().Insert(user);
        return Ok(user);
    }
}

3. Send Email with Azure Communication

public class NotificationController : ControllerBase
{
    private readonly IAzureCommunicationService _comm;

    [HttpPost("welcome-email")]
    public async Task<IActionResult> SendWelcomeEmail([FromBody] string email)
    {
        await _comm.SendEmailAsync(
            recipients: new[] { email },
            subject: "Welcome to Our Platform!",
            htmlContent: "<h1>Welcome!</h1><p>Thanks for joining us.</p>"
        );

        return Ok("Email sent successfully");
    }
}

4. Generate PDF Invoice

public class InvoiceController : ControllerBase
{
    private readonly IPdfService _pdf;

    [HttpGet("{id}/pdf")]
    public IActionResult GetInvoicePdf(string id)
    {
        var invoice = GetInvoiceData(id);
        var pdfBytes = _pdf.GeneratePdf(invoice);

        return File(pdfBytes, "application/pdf", $"invoice-{id}.pdf");
    }
}

5. Upload File to Cloud Storage

public class FilesController : ControllerBase
{
    private readonly ISupabaseService _supabase;
    private readonly IGoogleStorageService _gcs;

    [HttpPost("upload")]
    public async Task<IActionResult> Upload(IFormFile file)
    {
        using var stream = file.OpenReadStream();

        // Upload to Supabase
        var url = await _supabase.UploadFileAsync("uploads", file.FileName, stream);

        // Or upload to Google Cloud Storage
        // var result = await _gcs.UploadFilesAsync("my-bucket", file.FileName, stream);

        return Ok(new { url });
    }
}

---

⚙️ Configuration Guide

Minimal Configuration

{
  "ProjectName": "MyApp",
  "Env": "DEV",
  "Cors": {
    "AllowAny": true
  }
}

Complete Configuration

See appsettings.example.json for all available options.

Environment-Specific Configuration

Create environment-specific config files:

• appsettings.Development.json - Local development
• appsettings.Staging.json - Staging environment
• appsettings.Production.json - Production environment

Example - Development with open CORS:

{
  "Cors": {
    "AllowAny": true
  },
  "Serilog": {
    "serverUrl": "http://localhost:5341"
  }
}

Example - Production with restricted CORS:

{
  "Cors": {
    "AllowAny": false,
    "Origins": [
      "https://myapp.com",
      "https://www.myapp.com",
      "https://admin.myapp.com"
    ]
  }
}

---

🔐 Security Features

CORS (Cross-Origin Resource Sharing)

The library automatically configures CORS based on your appsettings.json:

Development Mode (Allow All):

{
  "Cors": {
    "AllowAny": true
  }
}

Production Mode (Whitelist Origins):

{
  "Cors": {
    "AllowAny": false,
    "Origins": "https://myapp.com,https://www.myapp.com"
  }
}

Or as an array:

{
  "Cors": {
    "AllowAny": false,
    "Origins": [
      "https://myapp.com",
      "https://api.myapp.com"
    ]
  }
}

⚠️ Security Warning: Always set AllowAny: false in production and specify exact origins.

JWT Authentication

{
  "Jwt": {
    "SecretKey": "your-super-secret-key-at-least-32-characters-long",
    "ValidateIssuerSigningKey": true,
    "ValidIssuer": "https://myapp.com",
    "ValidateIssuer": true,
    "ValidAudience": "https://myapp.com",
    "ValidateAudience": true,
    "KeyDuration": 3600
  }
}

Usage:

[Authorize] // Requires JWT token
[ApiController]
public class SecureController : ControllerBase
{
    [HttpGet("protected")]
    public IActionResult GetProtectedData()
    {
        var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
        return Ok($"User ID: {userId}");
    }
}

Global Exception Handling

The library automatically catches and handles all exceptions with safe error responses:

• Development: Returns detailed error information
• Production: Returns generic error messages (no stack traces)
• All Environments: Logs exceptions to configured sinks

---

📖 Complete Documentation

Database & ORM

• 📖 Supabase EF Core Complete Guide - Scaffolding, migrations, best practices
• 📖 Database Usage Examples - MySQL, PostgreSQL, Supabase

Services

• 📖 Azure Communication Services Guide - Email & SMS setup
• 📖 Supabase Usage Guide - Database, Auth, Storage
• 📖 QuestPDF Example - PDF generation with invoice template

Configuration

• 📖 Complete Configuration Template
• 📖 Azure Communication Config Examples
• 📖 Supabase Configuration

Code Examples

• 📖 Example Program.cs - Full Program.cs setup
• 📖 Example Controller - Controller examples
• 📖 Integration Guide - Complete setup guide

For Other Platforms

• 📦 React/NPM Library Guide - Create similar library for React/TypeScript

---

🎯 What Gets Registered Automatically?

When you call builder.UseIPGStandard():

1. ✅ Configuration - Loads appsettings.json + environment configs
2. ✅ Logging - Serilog with Console, Debug, Seq, Application Insights
3. ✅ Services - Auto-registers all *Service and *Repository classes
4. ✅ Options - Binds configuration to strongly-typed options
5. ✅ Database - Entity Framework Core with retry logic
6. ✅ Hangfire - Background job processing (if enabled)
7. ✅ Swagger - OpenAPI documentation (if enabled)
8. ✅ API Versioning - URL segment versioning
9. ✅ AutoMapper - Registers all AutoMapper profiles
10. ✅ JSON - CamelCase with enum support
11. ✅ CORS - Cross-origin resource sharing
12. ✅ JWT - Authentication (if configured)

When you call app.UseIPGStandard():

1. ✅ Serilog Request Logging - Logs all HTTP requests
2. ✅ DbUp Migrations - Runs database migrations
3. ✅ Hangfire Dashboard - Available at /hangfire
4. ✅ Exception Handler - Global exception handling
5. ✅ Swagger UI - Available at /api/docs
6. ✅ Authentication & Authorization - JWT support
7. ✅ CORS Middleware - CORS policy enforcement
8. ✅ Trace ID Middleware - Request tracing

---

📦 Package Contents

Services (Services/)

• SupabaseService - Supabase integration
• AzureCommunicationService - Email & SMS
• GoogleStorageService - Google Cloud Storage
• AzureBlobStorageService - Azure Blob Storage
• GeneralService - Utility methods
• PdfService - PDF generation (QuestPDF)

Options (Options/)

• JwtOptions - JWT configuration
• HangfireOptions - Background jobs config
• SupabaseOptions - Supabase settings
• MySqlRetryOptions - MySQL retry policy
• PostgreSqlRetryOptions - PostgreSQL retry policy
• AzureCommunicationOptions - Email/SMS config
• AzureBlobStorageOptions - Azure storage config

Middleware (Middlewares/)

• TraceIdMiddleware - Request tracing

Helpers (Helpers/)

• SerilogUpgradeLog - Logging utilities
• HangfireCustomBasicAuthenticationFilter - Hangfire auth

---

🔍 Troubleshooting

CORS Errors

Problem: Frontend getting CORS errors

Solution: Add CORS configuration to appsettings.json:

{
  "Cors": {
    "AllowAny": false,
    "Origins": ["http://localhost:3000", "http://localhost:5173"]
  }
}

Service Not Found

Problem: Dependency injection fails for a service

Solution:

1. Ensure service configuration exists in appsettings.json
2. Check service is enabled (e.g., HangfireOptions.Enable = true)
3. Verify UseIPGStandard() is called in Program.cs

Swagger Not Showing

Problem: Swagger UI not available

Solution:

1. Set "Swagger": { "Enable": true } in appsettings.json
2. Navigate to /api/docs (not /swagger)

Database Connection Errors

Problem: Cannot connect to database

Solution:

1. Verify connection string in appsettings.json
2. Check database server is running
3. Ensure firewall allows connection
4. For Supabase: Use connection pooler URL (port 5432)

QuestPDF License Error

Problem: QuestPDF throws license error

Solution: Add to Program.cs before using any PDF services:

QuestPDF.Settings.License = LicenseType.Community; // Non-commercial
// or
QuestPDF.Settings.License = LicenseType.Professional; // Commercial (requires purchase)

---

📊 Supported Technologies

Category	Technologies
Databases	MySQL, PostgreSQL, Supabase (PostgreSQL), SQL Server
Cloud Storage	Google Cloud Storage, Azure Blob Storage, Supabase Storage
Email/SMS	Azure Communication Services, SMTP (FluentEmail)
Background Jobs	Hangfire (MySQL/PostgreSQL storage)
Logging	Serilog, Application Insights, Seq, Console, Debug
Authentication	JWT Bearer, OAuth (Apple, Google)
API Docs	Swagger/OpenAPI
PDF Generation	QuestPDF

---

📋 Requirements

• .NET 8.0 or higher
• ASP.NET Core 8.0+

---

📄 License

MIT License - See LICENSE file for details.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📞 Support

For issues or questions:

• Create an issue in the repository
• Check existing documentation in /Examples folder

---

🎉 Version History

v1.0.8 (Latest)

• ✨ Added QuestPDF for PDF generation
• ✨ Added Entity Framework Design package for scaffolding
• ✨ Added Supabase EF Core guide
• 📖 Enhanced documentation

v1.0.7

• ✨ Added Entity Framework Core support
• ✨ Added Supabase service examples

v1.0.0

• 🎉 Initial release

---

Built with ❤️ for rapid .NET development

⬆ Back to Top