Coject.Core.Helper 1.0.40

Coject.Core.Helper

A comprehensive .NET helper library providing essential utilities for file management, email operations, SMS services, data handling, encryption, and integration with cloud services.

Overview

Coject.Core.Helper is a production-ready utility library designed to streamline common development tasks in .NET applications. It offers robust implementations for file operations with advanced validation, email services, SMS integration, data manipulation, security features, and multiple storage provider support.

Features

📁 File Management

• Multiple Storage Providers: Support for AWS S3, FTP, and local file systems
• Advanced File Validation: Comprehensive validation with configurable size limits, extension restrictions, and format detection
• File Operations: Upload, download, delete, and manage files across different storage backends
• Digital Signatures: Generate and validate file signatures
• Format Support: Automatic file format detection from content (supports PDF, PNG, JPG, GIF, ZIP, BMP, DOCX)
• Shared Links: Generate temporary shared links with configurable expiry times
• Flexible Input: Support for both multipart form files and Base64 encoded content

📧 Email Services

• SMTP Integration: Send emails using MailKit with advanced configuration
• Template Support: Professional email signature generation
• Attachment Handling: Easy attachment management
• HTML/Plain Text: Support for both email formats

📱 SMS Integration

• Multi-Provider Support: Configurable SMS provider integration
• OTP Messages: Built-in support for one-time password delivery
• Flexible Response Handling: JSON or string-based success/error detection
• Custom Parameters: Configurable parameter names for different SMS gateways
• URL Encoding: Optional parameter encoding for compatibility

🔐 Security & Encryption

• Data Encryption: Secure encryption and decryption utilities with IV key support
• JWT Tokens: Token generation and validation
• Barcode Generation: Create barcodes using ZXing.Net
• Shared Link Security: Time-based expiry for secure file sharing
• File Validation: Prevent malicious file uploads with extension and size restrictions

📊 Data Utilities

• JSON Processing: Advanced JSON serialization and deserialization helpers
• Date Handling: Comprehensive date and time utilities
• String Operations: String manipulation and formatting tools
• Image Processing: Image handling and conversion utilities
• Map Data: Geographic data processing helpers

☁️ Cloud Integration

• AWS S3: Full support for Amazon S3 operations
• FTP: Traditional FTP server integration
• Configurable: Easy configuration for different storage providers

Installation

Install via NuGet Package Manager:

dotnet add package Coject.Core.Helper

Or via Package Manager Console:

Install-Package Coject.Core.Helper

Requirements

• .NET 8.0 or higher
• Dependencies are automatically installed via NuGet

Configuration

Application Settings Structure

Add the following configuration to your appsettings.json:

{
  "AttachmentSettings": {
    "StorageType": "FTP",
    "SharedLinkExpiryMinutes": 60,
    "EXPIRY_IV_KEY": "EXAMBELKEY",
    "MaxUploadSizeBytes": 52428800,
    "MaxUploadSizeMB": 50,
    "MaxFilesPerRequest": 10,
    "AllowedFileExtensions": [".pdf", ".jpg", ".jpeg", ".png", ".docx", ".xlsx", ".zip"],
    "FileSizeLimitsByExtension": {
      ".jpg": 10485760,
      ".jpeg": 10485760,
      ".png": 10485760,
      ".pdf": 20971520,
      ".docx": 20971520,
      ".xlsx": 20971520,
      ".zip": 104857600
    },
    "AWS": {
      "Key": "your-aws-access-key",
      "SecretKey": "your-aws-secret-key",
      "BucketName": "your-bucket-name"
    },
    "FTP": {
      "Server": "ftp://your-ftp-server.com",
      "Username": "ftp-username",
      "Password": "ftp-password"
    },
    "SmsSettings": {
      "Provider": "sms-provider-name",
      "BaseUrl": "https://sms-gateway.com/",
      "SendPath": "api/send",
      "UsernameParameter": "username",
      "PasswordParameter": "password",
      "SenderParameter": "Sender",
      "TextParameter": "Text",
      "NumberParameter": "number",
      "Username": "your-sms-username",
      "Password": "your-sms-password",
      "Sender": "YourAppName",
      "TimeoutSeconds": 30,
      "UrlEncodeParameters": true,
      "SuccessString": "",
      "SuccessCriteria": {
        "Type": "json",
        "SuccessProperty": "Status",
        "SuccessValue": "0"
      },
      "ErrorCriteria": {
        "Type": "string",
        "ErrorKeyword": "Error Code"
      },
      "OTPMessage": "Use the code {0} to log in."
    }
  }
}

Configuration Parameters

Storage Settings

Parameter	Type	Description
StorageType	string	Storage provider to use: "AWS", "FTP", or "Local"
SharedLinkExpiryMinutes	integer	Duration in minutes before shared links expire
EXPIRY_IV_KEY	string	Base64 encoded initialization vector for encryption

File Upload Validation Settings

Parameter	Type	Description
MaxUploadSizeBytes	long	Maximum file size in bytes (default: 52428800 = 50 MB)
MaxUploadSizeMB	integer	Maximum file size in megabytes for display purposes
MaxFilesPerRequest	integer	Maximum number of files allowed per upload request
AllowedFileExtensions	array	List of allowed file extensions (e.g., [".pdf", ".jpg"]). Leave empty to allow all extensions
FileSizeLimitsByExtension	object	Dictionary of extension-specific size limits in bytes

AWS S3 Settings

Parameter	Type	Description
Key	string	AWS access key ID
SecretKey	string	AWS secret access key
BucketName	string	S3 bucket name for file storage

FTP Settings

Parameter	Type	Description
Server	string	FTP server URL (include ftp:// or ftps://)
Username	string	FTP account username
Password	string	FTP account password

SMS Settings

Parameter	Type	Description
Provider	string	Name/identifier of the SMS provider
BaseUrl	string	Base URL of the SMS gateway API
SendPath	string	API endpoint path for sending SMS
UsernameParameter	string	Parameter name for username in API request
PasswordParameter	string	Parameter name for password in API request
SenderParameter	string	Parameter name for sender ID in API request
TextParameter	string	Parameter name for message text in API request
NumberParameter	string	Parameter name for recipient number in API request
Username	string	Your SMS gateway account username
Password	string	Your SMS gateway account password
Sender	string	Default sender name/ID for outgoing messages
TimeoutSeconds	integer	Request timeout duration (default: 30)
UrlEncodeParameters	boolean	Whether to URL encode parameters (default: true)
SuccessString	string	Optional string to match for success (legacy)
OTPMessage	string	Template for OTP messages. Use {0} for code placeholder

SMS Success Criteria

Parameter	Type	Description
Type	string	Response format: "json" or "string"
SuccessProperty	string	JSON property name to check for success (json type only)
SuccessValue	string	Expected value indicating success

SMS Error Criteria

Parameter	Type	Description
Type	string	Error detection format: "json" or "string"
ErrorKeyword	string	Keyword/property indicating an error occurred

Configuration Examples

Basic File Upload Configuration

{
  "AttachmentSettings": {
    "StorageType": "FTP",
    "MaxUploadSizeBytes": 52428800,
    "MaxUploadSizeMB": 50,
    "MaxFilesPerRequest": 10
  }
}

Restricted File Types Configuration

{
  "AttachmentSettings": {
    "MaxUploadSizeBytes": 52428800,
    "MaxFilesPerRequest": 5,
    "AllowedFileExtensions": [".pdf", ".jpg", ".jpeg", ".png"],
    "FileSizeLimitsByExtension": {
      ".jpg": 5242880,
      ".jpeg": 5242880,
      ".png": 5242880,
      ".pdf": 10485760
    }
  }
}

This configuration:

• Allows only PDF and image files
• Sets image files to max 5 MB
• Sets PDF files to max 10 MB
• Limits to 5 files per request

Using AWS S3 Storage

{
  "AttachmentSettings": {
    "StorageType": "AWS",
    "MaxUploadSizeBytes": 104857600,
    "MaxUploadSizeMB": 100,
    "AWS": {
      "Key": "AKIAIOSFODNN7EXAMPLE",
      "SecretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "BucketName": "my-application-files"
    }
  }
}

Using FTP Storage

{
  "AttachmentSettings": {
    "StorageType": "FTP",
    "MaxUploadSizeBytes": 52428800,
    "FTP": {
      "Server": "ftp://files.company.com",
      "Username": "fileadmin",
      "Password": "SecureP@ssw0rd"
    }
  }
}

SMS with JSON Response

{
  "AttachmentSettings": {
    "SmsSettings": {
      "SuccessCriteria": {
        "Type": "json",
        "SuccessProperty": "Status",
        "SuccessValue": "0"
      }
    }
  }
}

Expected API response:

{
  "Status": "0",
  "Message": "SMS sent successfully"
}

SMS with String Response

{
  "AttachmentSettings": {
    "SmsSettings": {
      "SuccessCriteria": {
        "Type": "string",
        "SuccessValue": "SUCCESS"
      },
      "ErrorCriteria": {
        "Type": "string",
        "ErrorKeyword": "ERROR"
      }
    }
  }
}

Expected API response: "SUCCESS: Message delivered"

Usage Scenarios

File Upload Operations

The library provides comprehensive file upload validation and management:

Upload validation: Files are automatically validated against configured size limits, allowed extensions, and extension-specific restrictions before upload

Multiple input formats: Supports both multipart form file uploads and Base64 encoded file content

Automatic format detection: The library can detect file formats from their binary signatures (magic numbers) for PDF, PNG, JPG, GIF, ZIP, BMP, and DOCX files

Size calculation: Automatically calculates file sizes for both FormFile and Base64Content inputs

Detailed error messages: Provides user-friendly error messages with actual file sizes in human-readable format (KB, MB, GB)

Batch validation: Validates multiple files in a single request, checking both individual file sizes and total upload size

File Validation Features

The CojectFile class provides automatic validation with the following checks:

1. Content Validation: Ensures either FormFile or Base64Content is provided (but not both)
2. Base64 Validation: Validates Base64 string format and structure
3. Size Validation: Checks file size against global and extension-specific limits
4. Extension Validation: Verifies file extensions against allowed list
5. Format Detection: Automatically detects file format from binary content
6. Total Size Validation: Validates total size when uploading multiple files

Storage Operations

Upload a file: Files are automatically routed to AWS S3, FTP, or local storage based on configuration

Download a file: Retrieve files from the configured storage provider

Generate shared link: Create temporary links with automatic expiry based on SharedLinkExpiryMinutes

Delete a file: Remove files from the configured storage backend

SMS Operations

Send OTP: The library uses the OTPMessage template to format one-time passwords

Send notifications: Send SMS messages through the configured provider

Custom parameters: The library maps your provider's parameter names using the configuration settings

Response validation: Automatically validates success/failure based on SuccessCriteria and ErrorCriteria

Email Operations

Send emails: SMTP integration with attachment support

Generate signatures: Professional email signature generation

HTML/Plain text: Support for both formats with template support

Encryption & Security

Encrypt data: Uses the configured EXPIRY_IV_KEY for secure encryption

Generate tokens: JWT token generation with configurable expiry

Shared links: Time-based security for temporary file access

File upload security: Prevents malicious uploads through extension and size restrictions

Validation Error Codes

The library returns standardized error codes for different validation scenarios:

Error Code	Description
CojectFileHandler-01	No files were provided for upload
CojectFileHandler-02	Exceeded maximum files per request limit
CojectFileHandler-03	File validation failed (size, extension, or format issues)
CojectFileHandler-04	Total upload size exceeds maximum allowed size

Example Error Responses

File size exceeds limit:

{
  "Messages": {
    "CODE": "CojectFileHandler-03",
    "MESSAGE": "Validation failed for 'document.pdf': File 'document.pdf' size (75.5 MB) exceeds maximum allowed size of 50 MB"
  }
}

Invalid file extension:

{
  "Messages": {
    "CODE": "CojectFileHandler-03",
    "MESSAGE": "Validation failed for 'script.exe': File extension '.exe' is not allowed. Allowed extensions: .pdf, .jpg, .jpeg, .png, .docx"
  }
}

Too many files:

{
  "Messages": {
    "CODE": "CojectFileHandler-02",
    "MESSAGE": "Maximum 10 files allowed per request. You provided 15 files."
  }
}

Extension-specific limit exceeded:

{
  "Messages": {
    "CODE": "CojectFileHandler-03",
    "MESSAGE": "Validation failed for 'photo.jpg': File 'photo.jpg' size (12 MB) exceeds maximum allowed size for .jpg files (10 MB)"
  }
}

Recommended Size Limits by File Type

File Type	Recommended Limit	Configuration Example
Images (JPG, PNG)	5-10 MB	10485760 bytes
Documents (PDF, DOCX)	10-20 MB	20971520 bytes
Spreadsheets (XLSX)	10-20 MB	20971520 bytes
Archives (ZIP, RAR)	50-100 MB	104857600 bytes
Videos	100-500 MB	524288000 bytes
General Files	50 MB	52428800 bytes

Project Structure

CojectCore.Helper/
├── API/
│   └── APIHelper.cs
├── EmailManager/
│   ├── Entity/
│   ├── Interface/
│   └── Service/
├── FileSignatures/
│   ├── Abstract/
│   ├── Formats/
│   ├── Interface/
│   └── Service/
├── FilesManager/
│   ├── Entity/
│   │   └── CojectFile.cs (with validation)
│   ├── Interface/
│   │   └── ICojectFileControllerHelper.cs
│   └── Service/
│       ├── CojectFileControllerHelper.cs (with validation)
│       ├── CojectFileManager.cs
│       ├── CojectFileManagerAWS.cs
│       ├── CojectFileManagerFTP.cs
│       └── CojectFileManagerHelper.cs
├── BarcodeHelper.cs
├── DateHelper.cs
├── EncryptionHelper.cs
├── FileHelper.cs
├── ImageHelper.cs
├── JsonHelper.cs
├── MapDataHelper.cs
├── SmsHelper.cs
└── StringHelper.cs

Dependencies

This package includes the following key dependencies:

• AWSSDK.S3 (v3.7.406.2) - Amazon S3 integration
• MailKit (v4.8.0) - Email operations
• MimeKit (v4.8.0) - MIME message handling
• Newtonsoft.Json (v13.0.3) - JSON serialization
• System.IdentityModel.Tokens.Jwt (v8.2.1) - JWT token handling
• ZXing.Net.Mobile (v2.4.1) - Barcode generation
• System.Drawing.Common (v9.0.0) - Image processing
• System.Data.SQLite (v1.0.119) - Database operations
• Microsoft.AspNetCore.Mvc (v2.2.0) - MVC framework support
• Coject.Core.Controller - Core controller functionality
• Coject.Core.Model - Data models

Best Practices

Security

1. Never hardcode credentials: Always use configuration files or environment variables
2. Secure configuration: Encrypt sensitive sections in production using .NET configuration encryption
3. IV Key rotation: Regularly rotate the EXPIRY_IV_KEY for enhanced security
4. Shared link expiry: Set appropriate SharedLinkExpiryMinutes based on your security requirements
5. File extension restrictions: Always define AllowedFileExtensions to prevent malicious file uploads
6. Validate file content: The library validates file content against declared extensions using magic numbers

Storage Configuration

1. Choose the right provider: AWS S3 for scalability, FTP for legacy systems, Local for development
2. Test connectivity: Verify storage provider credentials before deployment
3. Backup strategy: Implement proper backup procedures for your chosen storage type
4. Size limits: Consider storage provider limits (AWS S3 max single upload: 5GB, FTP varies by server)

File Upload Configuration

1. Set appropriate limits: Configure MaxUploadSizeBytes based on your application needs and server capacity
2. Use extension-specific limits: Define different size limits for different file types in FileSizeLimitsByExtension
3. Limit file count: Set MaxFilesPerRequest to prevent abuse and server overload
4. Whitelist extensions: Always specify AllowedFileExtensions for security
5. Monitor uploads: Log large upload attempts and validation failures
6. Test limits: Verify that Kestrel/IIS limits match your configuration settings

SMS Configuration

1. Provider compatibility: Ensure parameter names match your SMS gateway's API
2. Response validation: Test both success and error scenarios with your provider
3. URL encoding: Enable UrlEncodeParameters if your provider requires encoded values
4. Timeout settings: Adjust TimeoutSeconds based on provider response times
5. Message templates: Customize OTPMessage to match your application's branding

Performance

1. Async operations: The library uses async methods for all I/O operations
2. Connection pooling: Reuse connections when possible
3. Early validation: Files are validated before upload to save bandwidth and storage operations
4. Error handling: Implement proper try-catch blocks for network operations
5. Resource disposal: Ensure proper disposal of streams and connections
6. Caching: The helper caches configuration settings to avoid repeated reads

Troubleshooting

File Upload Issues

"Request size exceeds maximum allowed size"

• Check MaxUploadSizeBytes in appsettings.json
• Verify Kestrel/IIS MaxRequestBodySize matches configuration
• Ensure FormOptions.MultipartBodyLengthLimit is set correctly in Program.cs

"File extension not allowed"

• Add the extension to AllowedFileExtensions array
• Ensure extensions include the dot prefix (e.g., ".pdf" not "pdf")
• Check if extensions are case-sensitive in your configuration

"File size exceeds maximum for extension"

• Review FileSizeLimitsByExtension settings
• Ensure extension-specific limits are in bytes
• Verify the extension key matches exactly (including case)

"Validation failed: Base64Content is not valid"

• Ensure Base64 string is properly formatted
• Check if data URI prefix is included (e.g., "data:image/png;base64,...")
• Verify no whitespace or line breaks in Base64 string

"Total upload size exceeds limit"

• Reduce number of files per request
• Check combined size of all files against MaxUploadSizeBytes
• Consider implementing chunked uploads for large batches

Storage Issues

AWS S3 Connection Fails

• Verify Key and SecretKey are correct
• Ensure bucket exists and has proper permissions
• Check IAM policies for S3 access
• Verify bucket region matches configuration

FTP Connection Fails

• Verify server URL includes protocol (ftp:// or ftps://)
• Check username and password
• Ensure firewall allows FTP connections (typically port 21)
• Test passive vs active FTP mode

SMS Issues

Messages Not Sending

• Verify BaseUrl and SendPath are correct
• Check SMS provider credentials
• Ensure parameter names match provider's API
• Test API endpoint with provider's documentation

Success/Error Not Detected

• Review provider's response format
• Adjust SuccessCriteria.Type to match response (json/string)
• Verify property names and values are correct
• Check for case sensitivity in success/error values

Shared Link Issues

Links Expire Too Quickly

• Increase SharedLinkExpiryMinutes value
• Check server time synchronization
• Verify timezone settings

Encryption Errors

• Ensure EXPIRY_IV_KEY is valid Base64 string (16, 24, or 32 bytes when decoded)
• Verify key hasn't been modified or corrupted
• Check for whitespace in configuration value

Configuration Issues

Settings Not Loading

• Verify JSON syntax in appsettings.json
• Check for missing commas or brackets
• Ensure configuration section name matches exactly: "AttachmentSettings"
• Verify configuration is being read in Program.cs

Validation Not Working

• Ensure CojectFileControllerHelper is properly injected
• Verify ValidateFileUpload() is called before upload
• Check that settings are not null in helper class
• Review logs for validation error details

Versioning

This package follows Semantic Versioning (SemVer). Current version: 1.0.36

Support

For issues, feature requests, or contributions, please contact the development team at Akwad Arabia.

License

Copyright © Akwad Al-Arabia 2024. All rights reserved.

See LICENSE.txt for detailed license information.

Authors

Developed and maintained by Akwad Arabia

---

Part of the Coject Core ecosystem