Coject.Core.Helper 1.0.36

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, 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
• File Operations: Upload, download, delete, and manage files across different storage backends
• Digital Signatures: Generate and validate file signatures
• Format Support: Handle various file formats with dedicated helpers
• Shared Links: Generate temporary shared links with configurable expiry times

📧 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

📊 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": "ByDz579cdbMMZq8cbzMhtA==",
    "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

AWS S3 Settings

FTP Settings

SMS Settings

SMS Success Criteria

SMS Error Criteria

Configuration Examples

Using AWS S3 Storage

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

Using FTP Storage

{
  "AttachmentSettings": {
    "StorageType": "FTP",
    "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 Storage Operations

The library automatically uses the configured storage provider based on the StorageType setting:

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

Project Structure

CojectCore.Helper/
├── API/
│   └── APIHelper.cs
├── EmailManager/
│   ├── Entity/
│   ├── Interface/
│   └── Service/
├── FileSignatures/
│   ├── Abstract/
│   ├── Formats/
│   ├── Interface/
│   └── Service/
├── FilesManager/
│   ├── Entity/
│   ├── Interface/
│   └── Service/
│       ├── CojectFileControllerHelper.cs
│       ├── 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
• 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

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

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. Error handling: Implement proper try-catch blocks for network operations
4. Resource disposal: Ensure proper disposal of streams and connections

Troubleshooting

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

FTP Connection Fails

• Verify server URL includes protocol (ftp:// or ftps://)
• Check username and password
• Ensure firewall allows FTP connections

SMS Issues

Messages Not Sending

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

Success/Error Not Detected

• Review provider's response format
• Adjust SuccessCriteria.Type to match response (json/string)
• Verify property names and values are correct

Shared Link Issues

Links Expire Too Quickly

• Increase SharedLinkExpiryMinutes value
• Check server time synchronization

Encryption Errors

• Ensure EXPIRY_IV_KEY is valid Base64 string
• Verify key hasn't been modified or corrupted

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