CG.Infrastructure.Services 3.10.6

CG.Infrastructure.Services

A comprehensive .NET library providing a collection of utility services for common application tasks including serialization, string manipulation, console operations, and more.

Overview

CG.Infrastructure.Services provides a set of reusable, well-tested services that handle common infrastructure concerns in .NET applications. These services are designed to be lightweight, performant, and easy to integrate into any .NET project.

Features

• Serialization Services: JSON serialization and deserialization with error handling and dynamic object support
• String Manipulation: Advanced string operations, splitting, trimming, and comparison
• Console Operations: Console table creation and output formatting
• Document Processing: File and document handling utilities
• Security Services: Secure string handling and comparison
• Extension Methods: Convenient extension methods for common operations
• Message System: Base message infrastructure for communication patterns

Requirements

• .NET 9.0 or later
• CG.Infrastructure.Core 3.10.7 or later
• Newtonsoft.Json 13.0.3 or later
• ConsoleTables 2.7.0 or later

Installation

dotnet add package CG.Infrastructure.Services

Quick Start

1. Register Services

using Infrastructure.Services.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Add infrastructure services
builder.Services.AddInfrastructureServices();

var app = builder.Build();
app.Run();

2. Use Services

public class UserController : ControllerBase
{
    private readonly ISerializationService _serializationService;
    private readonly ISubstringService _substringService;
    
    public UserController(ISerializationService serializationService, ISubstringService substringService)
    {
        _serializationService = serializationService;
        _substringService = substringService;
    }
    
    [HttpPost]
    public IActionResult CreateUser([FromBody] CreateUserRequest request)
    {
        // Serialize the request for logging
        var json = _serializationService.SerializeObject(request);
        
        // Process string operations
        var cleanEmail = _substringService.FixString(request.Email);
        
        // Continue with user creation...
    }
}

Core Services

SerializationService

Handles JSON serialization and deserialization with comprehensive error handling and null safety.

Features

• Null Safety: All methods include proper null parameter validation
• Error Handling: Graceful fallbacks with detailed logging
• Type Safety: Generic methods for type-safe operations
• Collection Support: Specialized handling for ObservableCollection

Methods

public interface ISerializationService
{
    // Serialize any object to JSON
    string SerializeObject<TEntity>(TEntity entity);
    
    // Deserialize JSON to strongly-typed object
    TEntity? DeserialiseObject<TEntity>(string json);
    
    // Deserialize JSON to ObservableCollection
    ObservableCollection<TEntity> DeserialiseCollection<TEntity>(string json);
    
    // Deserialize unknown JSON structure as dynamic object
    dynamic? DeserialiseUnknownObject<TObject>(string? json);
    
    // Format JSON string with proper indentation
    string GetFormattedString(string json);
    
    // Read and parse JSON file as JToken
    JToken GetObjectFromFile(string jsonFile);
    
    // Read and parse JSON file as dynamic object (easier property access)
    dynamic? GetObjectFromFileAsDynamic(string jsonFile);
}

Usage Examples

var serializationService = serviceProvider.GetRequiredService<ISerializationService>();

// Serialize object
var user = new User { Id = 1, Name = "John Doe" };
var json = serializationService.SerializeObject(user);

// Deserialize object
var deserializedUser = serializationService.DeserialiseObject<User>(json);

// Handle collections
var users = serializationService.DeserialiseCollection<User>(jsonArray);

// Format JSON
var formattedJson = serializationService.GetFormattedString(uglyJson);

// Read from file as JToken
var config = serializationService.GetObjectFromFile("config.json");
var value = config["setting"]?.ToString();

// Read from file as dynamic (easier property access)
var dynamicConfig = serializationService.GetObjectFromFileAsDynamic("config.json");
var dynamicValue = dynamicConfig?.setting?.ToString();

// Handle unknown JSON structures dynamically
var unknownData = serializationService.DeserialiseUnknownObject<object>(jsonString);
if (unknownData != null)
{
    var propertyValue = unknownData.propertyName?.ToString();
}

SubstringService

Provides advanced string manipulation capabilities including splitting, trimming, and pattern matching.

Features

• Flexible Splitting: Multiple delimiter support with distinct options
• Pattern Matching: Token-based substring extraction
• String Cleaning: Automatic string normalization and fixing
• Comparison Options: Configurable string comparison behavior

Methods

public interface ISubstringService
{
    // Split string with multiple delimiters
    string[] SplitString(string inputText, string[] split, bool distinct = false, StringSplitOptions splitOptions = StringSplitOptions.RemoveEmptyEntries);
    
    // Extract substring between tokens
    string GetSubstring(string inputText, string? token1, string? token2);
    
    // Clean and normalize string
    string FixString(string inputText);
    
    // Trim string from start and end
    string Trim(string inputText, string startValue, string endValue, StringComparison comparisonType = StringComparison.CurrentCultureIgnoreCase);
    
    // Trim from start only
    string TrimStart(string inputText, string trimString, StringComparison comparisonType = StringComparison.CurrentCultureIgnoreCase);
    
    // Trim from end only
    string TrimEnd(string inputText, string trimString, StringComparison comparisonType = StringComparison.CurrentCultureIgnoreCase);
    
    // Remove text before specific token
    string RemoveTextBefore(string inputText, string trimString, StringComparison comparisonType = StringComparison.CurrentCultureIgnoreCase);
    
    // Remove text after specific token
    string RemoveTextAfter(string inputText, string trimString, StringComparison comparisonType = StringComparison.CurrentCultureIgnoreCase);
    
    // Count pattern occurrences
    int CountStringOccurrences(string inputText, string pattern);
    
    // Compare strings with options
    int CompareStrings(string inputText, string comparisonText, StringComparison comparisonType = StringComparison.CurrentCultureIgnoreCase);
    
    // Check string equality with options
    bool EqualStrings(string inputText, string equalText, StringComparison comparisonType = StringComparison.CurrentCultureIgnoreCase);
}

Usage Examples

var substringService = serviceProvider.GetRequiredService<ISubstringService>();

// Split with multiple delimiters
var parts = substringService.SplitString("apple,banana;cherry:grape", new[] { ",", ";", ":" });

// Extract between tokens
var content = substringService.GetSubstring("<tag>content</tag>", "<tag>", "</tag>");

// Clean string
var cleanText = substringService.FixString("  Hello   World  ");

// Trim specific values
var trimmed = substringService.Trim("HelloWorld", "Hello", "World");

// Count occurrences
var count = substringService.CountStringOccurrences("hello world hello", "hello");

ConsoleService

Creates formatted console tables for data display and reporting.

Features

• Table Formatting: Professional-looking console tables
• Alignment Options: Configurable column alignment
• Alternative Rows: Optional alternating row styling
• Generic Support: Works with any collection type

Methods

public interface IConsoleService
{
    // Create formatted console table
    void CreateConsoleTable<TEntity>(List<TEntity> data, string alignment, bool alternative);
}

Usage Examples

var consoleService = serviceProvider.GetRequiredService<IConsoleService>();

var users = new List<User>
{
    new User { Id = 1, Name = "John", Email = "john@example.com" },
    new User { Id = 2, Name = "Jane", Email = "jane@example.com" }
};

// Create table with center alignment and alternating rows
consoleService.CreateConsoleTable(users, "center", true);

DocumentService

Handles document processing and file operations.

Features

• File Operations: Safe file reading and writing
• Document Processing: Text and content manipulation
• Error Handling: Graceful failure handling
• Logging: Comprehensive operation logging

Methods

public interface IDocumentService
{
    // Read file content
    string ReadFile(string filePath);
    
    // Write content to file
    void WriteFile(string filePath, string content);
    
    // Append content to file
    void AppendToFile(string filePath, string content);
    
    // Check if file exists
    bool FileExists(string filePath);
    
    // Get file information
    FileInfo? GetFileInfo(string filePath);
}

SecureStringService

Provides secure string handling for sensitive data.

Features

• Secure Storage: Uses SecureString for sensitive data
• Safe Comparison: Constant-time string comparison
• Memory Protection: Automatic memory clearing
• Disposal: Proper resource cleanup

Methods

public interface ISecureStringService
{
    // Convert string to SecureString
    SecureString ToSecureString(string input);
    
    // Convert SecureString back to string
    string FromSecureString(SecureString secureString);
    
    // Secure string comparison
    bool SecureEquals(SecureString str1, SecureString str2);
}

IntegerService

Handles integer operations and conversions.

Features

• Safe Conversion: TryParse-based conversions
• Range Validation: Min/max value checking
• Formatting: Number formatting utilities
• Validation: Input validation helpers

Methods

public interface IIntegerService
{
    // Safe string to int conversion
    int? TryParseInt(string value);
    
    // Check if value is in range
    bool IsInRange(int value, int min, int max);
    
    // Format number with separators
    string FormatNumber(int number);
}

CompareService

Provides comparison utilities for various data types.

Methods

public interface ICompareService
{
    // Compare two objects
    int Compare(object obj1, object obj2);
}

OutputService

Handles output formatting and display.

Methods

public interface IOutputService
{
    // Format output with options
    string FormatOutput(object data, string format);
}

Extension Methods

SerializationExtensions

// Convert any object to JSON
var json = user.ToJson();

// Compare objects by JSON representation
bool areEqual = user1.CompareJson(user2);

IntegerExtensions

// Safe integer conversion
int? number = "123".ToInt();

// Range validation
bool isValid = 50.IsBetween(0, 100);

StringExtensions

// String manipulation
var result = "Hello World".RemoveTextBefore("World");

// Pattern counting
var count = "hello world".CountOccurrences("o");

DateExtensions

// Date utilities
var isWeekend = DateTime.Now.IsWeekend();
var isBusinessDay = DateTime.Now.IsBusinessDay();

EnumExtensions

// Enum utilities
var description = MyEnum.Value1.GetDescription();
var values = EnumExtensions.GetValues<MyEnum>();

Configuration

Service Registration

// Register all services
builder.Services.AddInfrastructureServices();

// Register specific services
builder.Services.AddScoped<ISerializationService, SerializationService>();
builder.Services.AddScoped<ISubstringService, SubstringService>();
builder.Services.AddScoped<IConsoleService, ConsoleService>();

Dependency Injection

public class MyService
{
    private readonly ISerializationService _serializationService;
    private readonly ISubstringService _substringService;
    
    public MyService(ISerializationService serializationService, ISubstringService substringService)
    {
        _serializationService = serializationService;
        _substringService = substringService;
    }
}

Best Practices

1. Service Usage

• Use interfaces: Always depend on interfaces, not concrete implementations
• Single responsibility: Each service has a focused purpose
• Error handling: Services include comprehensive error handling
• Logging: All operations are logged for debugging

2. Performance Considerations

• Lazy loading: Services are created only when needed
• Memory management: Proper disposal of resources
• Efficient algorithms: Optimized string and collection operations

3. Security

• Input validation: All inputs are validated
• Secure defaults: Sensitive operations have secure defaults
• Resource cleanup: Automatic cleanup of sensitive data

Integration Examples

1. ASP.NET Core Web API

[ApiController]
[Route("api/[controller]")]
public class DataController : ControllerBase
{
    private readonly ISerializationService _serializationService;
    
    public DataController(ISerializationService serializationService)
    {
        _serializationService = serializationService;
    }
    
    [HttpPost("process")]
    public IActionResult ProcessData([FromBody] object data)
    {
        try
        {
            var json = _serializationService.SerializeObject(data);
            var formatted = _serializationService.GetFormattedString(json);
            
            return Ok(new { processed = true, formatted });
        }
        catch (Exception ex)
        {
            return BadRequest(new { error = ex.Message });
        }
    }
}

2. Console Application

class Program
{
    static async Task Main(string[] args)
    {
        var services = new ServiceCollection();
        services.AddInfrastructureServices();
        
        var serviceProvider = services.BuildServiceProvider();
        var consoleService = serviceProvider.GetRequiredService<IConsoleService>();
        
        var data = new List<Person>
        {
            new Person { Name = "John", Age = 30 },
            new Person { Name = "Jane", Age = 25 }
        };
        
        consoleService.CreateConsoleTable(data, "left", true);
    }
}

3. Background Service

public class DataProcessingService : BackgroundService
{
    private readonly ISerializationService _serializationService;
    private readonly ISubstringService _substringService;
    
    public DataProcessingService(ISerializationService serializationService, ISubstringService substringService)
    {
        _serializationService = serializationService;
        _substringService = substringService;
    }
    
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Process data using services
            var json = _serializationService.SerializeObject(new { timestamp = DateTime.UtcNow });
            var cleanJson = _substringService.FixString(json);
            
            await Task.Delay(1000, stoppingToken);
        }
    }
}

Migration to Newtonsoft.Json

This library uses Newtonsoft.Json for comprehensive JSON handling with dynamic object support.

Key Benefits

• Dynamic Object Support: Full runtime dynamic object access with dot notation
• Flexible JSON Handling: JToken provides flexible JSON structure manipulation
• Mature Library: Extensive features and excellent compatibility
• Runtime Flexibility: Access unknown JSON properties dynamically at runtime
• Better Error Handling: Comprehensive error handling and fallback options

Dynamic Object Features

• DeserialiseUnknownObject() returns dynamic? for runtime property access
• GetObjectFromFile() returns JToken for programmatic JSON manipulation
• GetObjectFromFileAsDynamic() returns dynamic? for easy property access
• All methods provide proper null handling and error recovery

Dynamic Object Usage

// Access properties on unknown JSON dynamically
var dynamicData = serializationService.DeserialiseUnknownObject<object>(json);
if (dynamicData != null)
{
    var stringValue = dynamicData.propertyName?.ToString();
    var intValue = (int?)dynamicData.number;
    var nestedValue = dynamicData.nested?.subProperty?.ToString();
}

// Read JSON file as dynamic object
var guildData = serializationService.GetObjectFromFileAsDynamic("guild.json");
if (guildData != null)
{
    var memberCount = (int?)guildData.data?.members?.Count;
    var guildName = guildData.data?.guild_name?.ToString();
    
    // Access nested properties easily
    foreach (var member in guildData.data?.members ?? new dynamic[0])
    {
        var allyCode = member.ally_code?.ToString();
        var playerName = member.player_name?.ToString();
        
        if (!string.IsNullOrEmpty(allyCode))
        {
            // Process member data...
        }
    }
}

JToken Usage

// Access properties programmatically with JToken
var config = serializationService.GetObjectFromFile("config.json");
if (config is JObject jObject)
{
    var setting = jObject["setting"]?.ToString();
    var number = jObject["number"]?.Value<int>();
    
    // Check property existence
    if (jObject.ContainsKey("optional"))
    {
        var optionalValue = jObject["optional"]?.ToString();
    }
}

Benefits of Newtonsoft.Json:

• True Dynamic Objects: Runtime property access with dot notation
• Flexible JSON Handling: JToken handles any JSON structure
• Better Error Recovery: Graceful handling of malformed JSON
• Runtime Flexibility: Access unknown properties without compile-time knowledge
• Mature Ecosystem: Extensive documentation and community support

When to Use Each Approach:

• Use GetObjectFromFile (JToken) when you need:

  • Programmatic JSON manipulation
  • Property existence checking
  • Type-safe property access
  • JSON structure validation

• Use GetObjectFromFileAsDynamic when you need:

  • Easy property access with dot notation
  • Runtime property discovery
  • Dynamic property access
  • Simplified JSON navigation

• Use DeserialiseUnknownObject when you need:

  • Handle completely unknown JSON structures
  • Runtime property exploration
  • Dynamic data processing
  • Flexible JSON handling

## Performance Considerations

### 1. Service Performance

- **Lightweight**: Services are designed to be lightweight
- **Efficient algorithms**: Optimized for common use cases
- **Memory efficient**: Minimal memory footprint
- **Fast execution**: Optimized for performance
- **JsonSerializerSettings caching**: Cached settings for optimal performance

### 2. Caching Strategy

- **No built-in caching**: Services are stateless
- **External caching**: Use external caching solutions as needed
- **Memory management**: Proper disposal of resources

### 3. Scalability

- **Stateless design**: Services can be easily scaled
- **Thread safety**: Safe for concurrent usage
- **Resource pooling**: Efficient resource utilization

### 4. Performance Optimizations

- **JsonSerializerSettings caching**: Static, cached settings prevent repeated configuration
- **No object allocation overhead**: Reuses the same settings instance
- **Consistent serialization behavior**: All operations use identical settings
- **Dynamic object optimization**: Efficient runtime property access

## Dependencies

- **CG.Infrastructure.Core**: Core infrastructure services and interfaces
- **Newtonsoft.Json**: Comprehensive JSON serialization and parsing with dynamic object support
- **ConsoleTables**: Console table formatting
- **Microsoft.Extensions.Logging**: Structured logging support

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Version History

- **3.10.2**: Current release with comprehensive service collection
- **3.10.1**: Initial release with basic services
- **3.10.0**: Foundation release

## Support

For questions, issues, or contributions, please visit our [GitHub repository](https://github.com/your-username/your-repo) or contact the development team.

## Related Packages

- `CG.Infrastructure.Core` - Core infrastructure services
- `CG.Infrastructure.Configuration` - Configuration management
- `CG.Infrastructure.Logging` - Logging infrastructure
- `CG.Infrastructure.Exceptions` - Exception handling